workflow 5.0.0-beta.1 → 5.0.0-beta.10

package/docs/cookbook/common-patterns/rate-limiting.mdx

@@ -0,0 +1,228 @@
+---
+title: Rate Limiting & Retries
+description: Handle 429 responses and transient failures with RetryableError and exponential backoff.
+type: guide
+summary: When an external API returns 429, throw RetryableError with the Retry-After value so the workflow runtime automatically reschedules the step after the specified delay.
+---
+
+Use this pattern when calling external APIs that enforce rate limits. Instead of writing manual retry loops, throw `RetryableError` with a `retryAfter` value and let the workflow runtime handle rescheduling.
+
+## When to use this
+
+- Calling APIs that return 429 (Too Many Requests) with `Retry-After` headers
+- Any step that hits transient failures and needs backoff
+- Syncing data with third-party services (Stripe, CRMs, scrapers)
+
+## Pattern: RetryableError with Retry-After
+
+A step function calls an external API. On 429, it reads the `Retry-After` header and throws `RetryableError`. The runtime reschedules the step automatically.
+
+```typescript
+import { RetryableError } from "workflow";
+
+declare function fetchFromCrm(contactId: string): Promise<unknown>; // @setup
+declare function upsertToWarehouse(contactId: string, contact: unknown): Promise<void>; // @setup
+
+export async function syncContact(contactId: string) {
+  "use workflow";
+
+  const contact = await fetchFromCrm(contactId);
+  await upsertToWarehouse(contactId, contact);
+
+  return { contactId, status: "synced" };
+}
+```
+
+### Step function with rate limit handling
+
+```typescript
+import { RetryableError } from "workflow";
+
+async function fetchFromCrm(contactId: string) {
+  "use step";
+
+  const res = await fetch(`https://crm.example.com/contacts/${contactId}`);
+
+  if (res.status === 429) { // [!code highlight]
+    const retryAfter = res.headers.get("Retry-After");
+    throw new RetryableError("Rate limited by CRM", { // [!code highlight]
+      retryAfter: retryAfter ? parseInt(retryAfter) * 1000 : "1m",
+    });
+  }
+
+  if (!res.ok) throw new Error(`CRM returned ${res.status}`);
+  return res.json();
+}
+
+async function upsertToWarehouse(contactId: string, contact: unknown) {
+  "use step";
+  await fetch(`https://warehouse.example.com/contacts/${contactId}`, {
+    method: "PUT",
+    body: JSON.stringify(contact),
+  });
+}
+```
+
+## Pattern: Exponential backoff
+
+Use `getStepMetadata()` to access the current attempt number and calculate increasing delays:
+
+```typescript
+import { RetryableError, getStepMetadata } from "workflow";
+
+async function callFlakeyApi(endpoint: string) {
+  "use step";
+
+  const { attempt } = getStepMetadata(); // [!code highlight]
+  const res = await fetch(endpoint);
+
+  if (res.status === 429 || res.status >= 500) {
+    throw new RetryableError(`Request failed (${res.status})`, { // [!code highlight]
+      retryAfter: (attempt ** 2) * 1000, // 1s, 4s, 9s... // [!code highlight]
+    });
+  }
+
+  return res.json();
+}
+```
+
+## Pattern: Circuit breaker with sleep
+
+When a dependency is completely down, stop hitting it for a cooldown period using `sleep()`, then probe with a single test request:
+
+```typescript
+import { sleep } from "workflow";
+
+export async function circuitBreaker(maxRequests: number = 10) {
+  "use workflow";
+
+  let state: "closed" | "open" | "half-open" = "closed";
+  let consecutiveFailures = 0;
+  const FAILURE_THRESHOLD = 3;
+
+  for (let i = 1; i <= maxRequests; i++) {
+    if (state === "open") {
+      await sleep("30s"); // Durable cooldown // [!code highlight]
+      state = "half-open";
+    }
+
+    const success = await callService(i);
+
+    if (success) {
+      consecutiveFailures = 0;
+      if (state === "half-open") state = "closed";
+    } else {
+      consecutiveFailures++;
+      if (consecutiveFailures >= FAILURE_THRESHOLD) {
+        state = "open";
+        consecutiveFailures = 0;
+      }
+    }
+  }
+
+  return { status: state === "closed" ? "recovered" : "failed" };
+}
+
+async function callService(requestNum: number): Promise<boolean> {
+  "use step";
+  try {
+    const res = await fetch("https://payment-gateway.example.com/charge");
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+```
+
+## Pattern: Custom max retries
+
+Override the default retry count (3) for steps that need more or fewer attempts:
+
+```typescript
+async function fetchWithRetries(url: string) {
+  "use step";
+  const res = await fetch(url);
+  if (!res.ok) throw new Error(`Failed: ${res.status}`);
+  return res.json();
+}
+
+// Allow up to 10 retry attempts
+fetchWithRetries.maxRetries = 10; // [!code highlight]
+```
+
+## Application-level retry
+
+Sometimes you need retry logic at the workflow level -- wrapping a step call with your own backoff instead of relying on the framework's built-in `RetryableError`. This is useful when you want full control over retry conditions, delays, and error filtering.
+
+```typescript
+interface RetryOptions {
+  maxRetries?: number;
+  baseDelay?: number;
+  maxDelay?: number;
+  shouldRetry?: (error: Error, attempt: number) => boolean;
+}
+
+async function withRetry<T>(
+  fn: () => Promise<T>,
+  options: RetryOptions = {},
+): Promise<T> {
+  const { maxRetries = 3, baseDelay = 2000, maxDelay = 10000, shouldRetry } = options;
+  let lastError: Error | undefined;
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error instanceof Error ? error : new Error(String(error));
+      const isLastAttempt = attempt === maxRetries;
+      if (isLastAttempt || (shouldRetry && !shouldRetry(lastError, attempt + 1))) {
+        throw lastError;
+      }
+      // Exponential backoff with jitter
+      const delay = Math.min(baseDelay * 2 ** attempt * (0.5 + Math.random() * 0.5), maxDelay);
+      await new Promise(resolve => setTimeout(resolve, delay));
+    }
+  }
+
+  throw lastError;
+}
+```
+
+Use it in a workflow to wrap step calls:
+
+```typescript
+declare function withRetry<T>(fn: () => Promise<T>, options?: { maxRetries?: number; shouldRetry?: (error: Error) => boolean }): Promise<T>; // @setup
+declare function downloadFile(url: string): Promise<any>; // @setup
+
+export async function downloadWithRetry(url: string) {
+  "use workflow";
+
+  const result = await withRetry(() => downloadFile(url), { // [!code highlight]
+    maxRetries: 5,
+    shouldRetry: (error) => error.message.includes("Timeout"),
+  });
+
+  return result;
+}
+```
+
+**When to use this vs `RetryableError`/`FatalError`:**
+- **`RetryableError`** runs inside a step -- the framework reschedules the step after the delay. Use it for transient HTTP errors (429, 503) where the runtime should handle backoff.
+- **Application-level retry** wraps the step call from the workflow. Use it when you need custom retry conditions, want to retry across different steps, or when you're building a library and prefer not to depend on workflow-specific error classes.
+
+## Tips
+
+- **`RetryableError` is for transient failures.** Use it when the request might succeed on a later attempt (429, 503, network timeout).
+- **`FatalError` is for permanent failures.** Use it when retrying won't help (404, 401, invalid input). This skips all remaining retries.
+- **The `retryAfter` option accepts** a millisecond number, a duration string (`"1m"`, `"30s"`), or a `Date` object.
+- **Steps retry up to 3 times by default.** Set `fn.maxRetries = N` to change this per step function.
+- **Don't write manual sleep-retry loops.** The runtime handles scheduling natively with `RetryableError` -- it's more efficient and survives cold starts.
+
+## Key APIs
+
+- [`"use workflow"`](/docs/foundations/workflows-and-steps) -- marks the orchestrator function
+- [`"use step"`](/docs/foundations/workflows-and-steps) -- marks functions that run with full Node.js access
+- [`RetryableError`](/docs/api-reference/workflow/retryable-error) -- signals the runtime to retry after a delay
+- [`FatalError`](/docs/api-reference/workflow/fatal-error) -- signals a permanent failure, skipping retries
+- [`getStepMetadata()`](/docs/api-reference/step/get-step-metadata) -- provides the current attempt number and step ID
+- [`sleep()`](/docs/api-reference/workflow/sleep) -- durable pause for circuit breaker cooldowns

package/docs/cookbook/common-patterns/saga.mdx

@@ -0,0 +1,247 @@
+---
+title: Transactions & Rollbacks (Saga)
+description: Coordinate multi-step transactions with automatic rollback when a step fails.
+type: guide
+summary: Run a sequence of steps where each registers a compensation. If any step throws a FatalError, compensations execute in reverse order to restore consistency.
+---
+
+Use the saga pattern when a business transaction spans multiple services and you need automatic rollback if any step fails. Each forward step registers a compensation, and on failure the workflow unwinds them in reverse order.
+
+## When to use this
+
+- Multi-service transactions (reserve inventory, charge payment, provision access)
+- Any sequence where partial completion leaves the system in an inconsistent state
+- Operations that need "all or nothing" semantics across external APIs
+
+## How it works
+
+1. Each forward step does work and registers a compensation function.
+2. If any step throws `FatalError`, the catch block runs compensations in reverse (LIFO) order to restore consistency.
+3. Regular errors are retried automatically (up to 3x by default). Use `FatalError` only for permanent failures where retrying won't help.
+
+## Pattern
+
+Each step returns a result and pushes a compensation handler onto a stack. If a later step throws a `FatalError`, the workflow catches it and executes compensations in LIFO order.
+
+```typescript
+import { FatalError } from "workflow";
+
+declare function reserveSeats(accountId: string, seats: number): Promise<string>; // @setup
+declare function releaseSeats(accountId: string, reservationId: string): Promise<void>; // @setup
+declare function captureInvoice(accountId: string, seats: number): Promise<string>; // @setup
+declare function refundInvoice(accountId: string, invoiceId: string): Promise<void>; // @setup
+declare function provisionSeats(accountId: string, seats: number): Promise<string>; // @setup
+declare function deprovisionSeats(accountId: string, entitlementId: string): Promise<void>; // @setup
+declare function sendConfirmation(accountId: string, invoiceId: string, entitlementId: string): Promise<void>; // @setup
+
+export async function subscriptionUpgradeSaga(accountId: string, seats: number) {
+  "use workflow";
+
+  const compensations: Array<() => Promise<void>> = [];
+
+  try {
+    const reservationId = await reserveSeats(accountId, seats);
+    compensations.push(() => releaseSeats(accountId, reservationId)); // [!code highlight]
+
+    const invoiceId = await captureInvoice(accountId, seats);
+    compensations.push(() => refundInvoice(accountId, invoiceId)); // [!code highlight]
+
+    const entitlementId = await provisionSeats(accountId, seats);
+    compensations.push(() => deprovisionSeats(accountId, entitlementId)); // [!code highlight]
+
+    // No compensation — notifications are fire-and-forget
+    await sendConfirmation(accountId, invoiceId, entitlementId);
+
+    return { status: "completed" };
+  } catch (error) {
+    // Unwind compensations in reverse (LIFO) order
+    for (const compensate of compensations.reverse()) { // [!code highlight]
+      await compensate(); // [!code highlight]
+    }
+
+    return { status: "rolled_back" };
+  }
+}
+```
+
+### Step functions
+
+Each step is a `"use step"` function with full Node.js access (fetch, fs, npm packages). Forward steps do the work and throw `FatalError` on permanent failure; compensation steps undo it and must be idempotent — safe to call multiple times if the workflow restarts mid-rollback.
+
+```typescript
+import { FatalError } from "workflow";
+
+// Forward steps
+
+async function reserveSeats(accountId: string, seats: number): Promise<string> {
+  "use step";
+  const res = await fetch(`https://api.example.com/seats/reserve`, {
+    method: "POST",
+    body: JSON.stringify({ accountId, seats }),
+  });
+  if (!res.ok) throw new FatalError("Seat reservation failed"); // [!code highlight]
+  const { reservationId } = await res.json();
+  return reservationId;
+}
+
+async function captureInvoice(accountId: string, seats: number): Promise<string> {
+  "use step";
+  const res = await fetch(`https://api.example.com/invoices`, {
+    method: "POST",
+    body: JSON.stringify({ accountId, seats }),
+  });
+  if (!res.ok) throw new FatalError("Invoice capture failed"); // [!code highlight]
+  const { invoiceId } = await res.json();
+  return invoiceId;
+}
+
+async function provisionSeats(accountId: string, seats: number): Promise<string> {
+  "use step";
+  const res = await fetch(`https://api.example.com/entitlements`, {
+    method: "POST",
+    body: JSON.stringify({ accountId, seats }),
+  });
+  if (!res.ok) throw new FatalError("Provisioning failed"); // [!code highlight]
+  const { entitlementId } = await res.json();
+  return entitlementId;
+}
+
+async function sendConfirmation(
+  accountId: string,
+  invoiceId: string,
+  entitlementId: string
+): Promise<void> {
+  "use step";
+  await fetch(`https://api.example.com/notifications`, {
+    method: "POST",
+    body: JSON.stringify({ accountId, invoiceId, entitlementId, template: "upgrade-complete" }),
+  });
+}
+
+// Compensation steps — must be idempotent
+
+async function releaseSeats(accountId: string, reservationId: string): Promise<void> {
+  "use step";
+  await fetch(`https://api.example.com/seats/release`, {
+    method: "POST",
+    body: JSON.stringify({ accountId, reservationId }),
+  });
+}
+
+async function refundInvoice(accountId: string, invoiceId: string): Promise<void> {
+  "use step";
+  await fetch(`https://api.example.com/invoices/${invoiceId}/refund`, {
+    method: "POST",
+    body: JSON.stringify({ accountId }),
+  });
+}
+
+async function deprovisionSeats(accountId: string, entitlementId: string): Promise<void> {
+  "use step";
+  await fetch(`https://api.example.com/entitlements/${entitlementId}`, {
+    method: "DELETE",
+    body: JSON.stringify({ accountId }),
+  });
+}
+```
+
+### Streaming step progress (optional)
+
+Use `getWritable()` to stream progress events to a UI so users can see each step execute in real time.
+
+```typescript
+import { FatalError } from "workflow";
+import { getWritable } from "workflow";
+
+type SagaEvent =
+  | { type: "step_start"; step: string }
+  | { type: "step_done"; step: string; detail: string }
+  | { type: "step_failed"; step: string; error: string }
+  | { type: "compensating"; step: string }
+  | { type: "compensated"; step: string }
+  | { type: "result"; status: "completed" | "rolled_back" };
+
+async function emit(event: SagaEvent) {
+  "use step";
+  const writer = getWritable<SagaEvent>().getWriter();
+  try {
+    await writer.write(event);
+  } finally {
+    writer.releaseLock();
+  }
+}
+
+declare function reserveSeats(accountId: string, seats: number): Promise<string>; // @setup
+declare function releaseSeats(accountId: string, reservationId: string): Promise<void>; // @setup
+declare function captureInvoice(accountId: string, seats: number): Promise<string>; // @setup
+declare function refundInvoice(accountId: string, invoiceId: string): Promise<void>; // @setup
+declare function provisionSeats(accountId: string, seats: number): Promise<string>; // @setup
+declare function deprovisionSeats(accountId: string, entitlementId: string): Promise<void>; // @setup
+declare function sendConfirmation(accountId: string, invoiceId: string, entitlementId: string): Promise<void>; // @setup
+
+export async function subscriptionUpgradeSaga(accountId: string, seats: number) {
+  "use workflow";
+
+  const compensations: Array<{ name: string; execute: () => Promise<void> }> = [];
+
+  try {
+    await emit({ type: "step_start", step: "Reserve Seats" });
+    const reservationId = await reserveSeats(accountId, seats);
+    compensations.push({ name: "Release Seats", execute: () => releaseSeats(accountId, reservationId) });
+    await emit({ type: "step_done", step: "Reserve Seats", detail: reservationId });
+
+    await emit({ type: "step_start", step: "Capture Invoice" });
+    const invoiceId = await captureInvoice(accountId, seats);
+    compensations.push({ name: "Refund Invoice", execute: () => refundInvoice(accountId, invoiceId) });
+    await emit({ type: "step_done", step: "Capture Invoice", detail: invoiceId });
+
+    await emit({ type: "step_start", step: "Provision Seats" });
+    const entitlementId = await provisionSeats(accountId, seats);
+    compensations.push({ name: "Deprovision Seats", execute: () => deprovisionSeats(accountId, entitlementId) });
+    await emit({ type: "step_done", step: "Provision Seats", detail: entitlementId });
+
+    // No compensation — notifications are fire-and-forget
+    await emit({ type: "step_start", step: "Send Confirmation" });
+    await sendConfirmation(accountId, invoiceId, entitlementId);
+    await emit({ type: "step_done", step: "Send Confirmation", detail: "sent" });
+
+    await emit({ type: "result", status: "completed" });
+    return { status: "completed" };
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : "Unknown error";
+    await emit({ type: "step_failed", step: "failed", error: errorMessage });
+
+    // Unwind compensations in reverse (LIFO) order
+    for (const comp of compensations.reverse()) {
+      await emit({ type: "compensating", step: comp.name });
+      await comp.execute();
+      await emit({ type: "compensated", step: comp.name });
+    }
+
+    await emit({ type: "result", status: "rolled_back" });
+    return { status: "rolled_back" };
+  }
+}
+```
+
+## Adapting to your use case
+
+- Replace the step functions with real API calls. Each `"use step"` function has full Node.js access.
+- Add or remove steps as needed — the pattern scales to any number of steps.
+- Make compensations idempotent — they may be retried if the workflow restarts mid-rollback.
+- The `emit()` calls and `SagaEvent` type are optional — remove them if you don't need real-time UI progress.
+
+## Tips
+
+- **Use `FatalError` for permanent failures.** Regular errors trigger automatic retries (up to 3 by default). Throw `FatalError` when retrying won't help (e.g., insufficient funds, invalid input).
+- **Make compensations idempotent.** If a compensation step is retried, it should produce the same result. Check whether the resource was already released before releasing it again.
+- **Compensation steps are also `"use step"` functions.** This makes them durable — if the workflow restarts mid-rollback, it resumes where it left off.
+- **Capture values in closures carefully.** Use block-scoped variables or copy values before pushing compensations to avoid referencing stale state.
+- **Notifications don't need compensations.** Fire-and-forget steps like sending emails or Slack messages typically don't register a compensation.
+
+## Key APIs
+
+- [`"use workflow"`](/docs/api-reference/workflow/use-workflow) -- declares the orchestrator function
+- [`"use step"`](/docs/api-reference/workflow/use-step) -- declares step functions with full Node.js access
+- [`FatalError`](/docs/api-reference/workflow/fatal-error) -- non-retryable error that triggers compensation
+- [`getWritable()`](/docs/api-reference/workflow/get-writable) -- streams data from workflows for real-time UI updates

package/docs/cookbook/common-patterns/scheduling.mdx

@@ -0,0 +1,129 @@
+---
+title: Sleep, Scheduling & Timed Workflows
+description: Use durable sleep to schedule actions minutes, hours, days, or weeks into the future.
+type: guide
+summary: Schedule future actions with durable sleep that survives cold starts, and race sleeps against hooks to let external events cancel the workflow early.
+---
+
+Workflow's `sleep()` is durable — it survives cold starts, restarts, and deployments. Combined with `defineHook()` and `Promise.race()`, it becomes the foundation for interruptible scheduled workflows like drip campaigns, reminders, and timed sequences.
+
+<Callout type="info">
+Scheduled workflows are still pinned to the deployment that started them. If you are building recurring or indefinitely running schedules that should adopt newer code over time, see [Versioning](/docs/foundations/versioning) for the explicit `deploymentId: "latest"` continuation pattern.
+</Callout>
+
+## When to use this
+
+- Sending emails on a schedule (drip campaigns, onboarding sequences, reminders)
+- Waiting for a deadline but allowing early cancellation
+- Any pattern where "do X, wait N hours, then do Y" needs to be both reliable and interruptible
+
+## Drip campaign with cancellation
+
+A drip campaign sends emails at intervals, sleeping between each. Each sleep races against a cancellation hook — if an external event fires the hook (e.g. user converts, unsubscribes), the campaign stops immediately.
+
+```typescript
+import { defineHook, sleep } from "workflow";
+
+// Hook that any API route can fire to cancel the drip
+export const cancelDrip = defineHook<{ reason?: string }>(); // [!code highlight]
+
+async function sendEmail(email: string, template: string): Promise<void> {
+  "use step";
+  await fetch("https://api.sendgrid.com/v3/mail/send", {
+    method: "POST",
+    headers: { Authorization: `Bearer ${process.env.SENDGRID_KEY}` },
+    body: JSON.stringify({ to: [{ email }], template_id: template }),
+  });
+}
+
+export async function emailSequence(email: string) {
+  "use workflow";
+
+  await sendEmail(email, "welcome");
+
+  // Race durable sleep against the cancellation hook
+  const hook = cancelDrip.create({ token: `cancel-drip:${email}` }); // [!code highlight]
+  const cancelled = await Promise.race([ // [!code highlight]
+    sleep("2d").then(() => false), // [!code highlight]
+    hook.then(() => true), // [!code highlight]
+  ]); // [!code highlight]
+  if (cancelled) return { status: "cancelled", email };
+
+  await sendEmail(email, "getting-started-tips");
+
+  // Create a fresh hook for the next sleep window
+  const hook2 = cancelDrip.create({ token: `cancel-drip:${email}` }); // [!code highlight]
+  const cancelled2 = await Promise.race([ // [!code highlight]
+    sleep("2d").then(() => false), // [!code highlight]
+    hook2.then(() => true), // [!code highlight]
+  ]); // [!code highlight]
+  if (cancelled2) return { status: "cancelled", email };
+
+  await sendEmail(email, "feature-highlights");
+
+  return { status: "drip-complete", email };
+}
+```
+
+### Cancelling from an API route
+
+Any server-side code can fire the hook by calling `.resume()` with the same token:
+
+```typescript
+import { cancelDrip } from "@/workflows/email-sequence";
+
+export async function POST(req: Request) {
+  const { email, reason } = await req.json();
+
+  if (!email) {
+    return Response.json({ error: "email is required" }, { status: 400 });
+  }
+
+  try {
+    await cancelDrip.resume(`cancel-drip:${email}`, { // [!code highlight]
+      reason: reason ?? "User completed action", // [!code highlight]
+    }); // [!code highlight]
+  } catch (error) {
+    const msg = error instanceof Error ? error.message.toLowerCase() : "";
+    if (msg.includes("not found") || msg.includes("expired")) {
+      return Response.json({
+        success: true,
+        email,
+        note: "No active drip found (already completed or cancelled)",
+      });
+    }
+    throw error;
+  }
+
+  return Response.json({ success: true, email });
+}
+```
+
+## How it works
+
+1. **Durable sleep** — `sleep("2d")` persists through restarts at zero compute cost. The workflow resumes precisely when the timer fires.
+2. **Hook creation** — `cancelDrip.create({ token })` registers a hook that resolves when any external system calls `.resume()` with the same token.
+3. **Race** — `Promise.race([sleep(...), hook])` blocks until either the timer fires or the hook is resumed, whichever comes first.
+4. **Fresh hooks per window** — after a sleep completes normally, the previous hook instance is consumed. A new `.create()` call registers a fresh hook for the next sleep window, reusing the same token.
+
+## Adapting to your use case
+
+- **Change durations** — replace `"2d"` with any duration string (`"1h"`, `"7d"`, `"30m"`) or a `Date` object for absolute times.
+- **Add more steps** — the pattern scales to any number of email-then-sleep pairs.
+- **Snooze instead of cancel** — resolve the hook with a `snooze` payload and sleep again: `sleep(new Date(Date.now() + payload.snoozeMs))`.
+- **Timeout any operation** — the same `Promise.race(sleep, work)` pattern works for adding deadlines to slow steps.
+- **Real providers** — swap the `sendEmail` step body for Resend, Postmark, or any HTTP API. The `"use step"` function has full Node.js access.
+
+## Tips
+
+- **`sleep()` accepts** duration strings (`"1d"`, `"2h"`, `"30s"`), milliseconds, or `Date` objects for sleeping until a specific time.
+- **Durable means durable.** A `sleep("7d")` workflow costs nothing while sleeping — no compute, no memory.
+- **Use `sleep()` in workflow context only.** Step functions cannot call `sleep()` directly. If a step needs a delay, use `setTimeout` inside the step.
+
+## Key APIs
+
+- [`"use workflow"`](/docs/foundations/workflows-and-steps) — marks the orchestrator function
+- [`"use step"`](/docs/foundations/workflows-and-steps) — marks functions that run with full Node.js access
+- [`sleep()`](/docs/api-reference/workflow/sleep) — durable wait (survives restarts, zero compute cost)
+- [`defineHook()`](/docs/api-reference/workflow/define-hook) — creates a typed hook that external systems can fire
+- [`Promise.race()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/race) — races sleep against hooks for interruptible waits