workflow 5.0.0-beta.4 → 5.0.0-beta.40

package/docs/comparisons/workflow-sdk-vs-aws-step-functions.mdx

@@ -0,0 +1,111 @@
+---
+title: Workflow SDK vs AWS Step Functions
+description: How the Workflow SDK compares to AWS Step Functions — plain TypeScript control flow versus declarative Amazon States Language JSON, plus a concept-mapping migration guide.
+type: conceptual
+summary: AWS Step Functions is a managed state-machine orchestrator authored in declarative ASL JSON. The Workflow SDK expresses the same orchestration as plain TypeScript.
+prerequisites:
+  - /docs/foundations/workflows-and-steps
+related:
+  - /docs/foundations/errors-and-retries
+  - /docs/foundations/hooks
+  - /worlds/vercel
+---
+
+[AWS Step Functions](https://docs.aws.amazon.com/step-functions/latest/dg/welcome.html) is a mature, managed orchestrator that runs **state machines defined in Amazon States Language (ASL)** — a declarative JSON DSL. The headline contrast with the Workflow SDK is the authoring model: you assemble a state machine (JSON or a visual editor) instead of writing plain control-flow code.
+
+<Callout type="info">
+**Choose the Workflow SDK** when you want orchestration as ordinary TypeScript (`await`, `if`, `Promise.all`, `try/catch`) that lives in your app, portable off a single cloud, with built-in streaming. **Choose Step Functions** when you're deep in the AWS ecosystem and want a managed engine with native optimized integrations to 200+ AWS services and the broadest compliance footprint.
+</Callout>
+
+## At a glance
+
+| | Workflow SDK | AWS Step Functions |
+| --- | --- | --- |
+| **Authoring** | Plain TypeScript: `"use workflow"` orchestrators calling `"use step"` functions | **Declarative ASL JSON** (or Workflow Studio visual editor / CDK) — not plain code |
+| **Durability model** | Event log + deterministic replay | Managed state machine. **Standard** = exactly-once, up to 1 year; **Express** = at-least-once, up to 5 minutes |
+| **Control flow** | `await`, `if`/`switch`, `Promise.all`, `try/catch` | `Task` / `Choice` / `Wait` / `Parallel` / `Map` states wired with `Next` |
+| **Where it runs** | Your platform (Vercel managed or self-host) | AWS-managed; tasks run in Lambda or 200+ integrated AWS services |
+| **Languages** | TypeScript / JS (Python beta) | ASL JSON for the machine; tasks can be any language (via Lambda) |
+| **Human-in-the-loop** | `createHook()` / `createWebhook()` | `.waitForTaskToken` callback (Standard only) |
+| **Streaming** | Native durable, resumable streaming to clients | No native client streaming |
+| **Versioning** | Runs pinned to immutable deployment | Published versions are immutable; aliases route (≤2 versions) for canary/rollback; **in-flight executions keep their start-time definition** |
+| **Portability** | Apache-2.0; runs anywhere Node runs | Proprietary, AWS-only; ASL is AWS-specific — high lock-in |
+| **Pricing** | SDK free; pay your platform | **Standard:** $0.025 / 1K state transitions. **Express:** $1 / M requests + GB-second duration |
+| **Limits** | 50 MB payload; 2 GB/run; no duration cap ([Vercel World limits](https://vercel.com/docs/workflows/pricing)) | 256 KB payload between states; Standard 25K history events / 1 year; Express 5 minutes |
+| **AI** | `WorkflowAgent` in the AI SDK; durable streaming | Bedrock integration + a preview AgentCore "InvokeHarness" task; no native client streaming |
+
+**What the limits mean in practice:** the 256 KB cap on payloads between states is the binding constraint for AI workloads — virtually any model context or tool transcript has to round-trip through S3 with claim-check plumbing — and Standard executions cap history at 25K events. The [Vercel World limits](https://vercel.com/docs/workflows/pricing) are 50 MB per payload and 2 GB of state per run.
+
+## Code vs. JSON
+
+The defining difference: in Step Functions even "call one Lambda" requires a state-machine shell, and orchestration logic is expressed as ASL states (`Choice`, `Wait`, `Parallel`, `Map`). In the Workflow SDK it's ordinary TypeScript — transitions are `await`, branches are `if`, parallelism is `Promise.all`, and error handling is `try/catch`. That keeps orchestration in the same language, repo, and tests as the rest of your app, and removes the orchestrator/compute split (per-task Lambdas, IAM roles, callback queues).
+
+The trade-off: Step Functions' optimized service integrations call AWS services (DynamoDB, SQS, EventBridge, Bedrock, `ecs:runTask.sync`, …) declaratively. In the Workflow SDK those become ordinary SDK calls inside `"use step"` functions — you own the credentials, retries, and any polling.
+
+## Migrating from Step Functions
+
+This guide assumes **Standard** workflows. Express workflows have different semantics (at-least-once, 5-minute max, no execution history) and may be better kept on Step Functions or moved to a queue consumer.
+
+| AWS Step Functions | Workflow SDK | Note |
+| --- | --- | --- |
+| State machine (ASL JSON) | `"use workflow"` function | The workflow function *is* the state machine. |
+| Task state / Lambda | `"use step"` function | Side effects go in steps; no separate Lambda. |
+| Choice state | `if` / `else` / `switch` | Native control flow. |
+| Wait state | `sleep()` | `sleep('1m')` or `sleep(date)`. |
+| Parallel state | `Promise.all()` | Standard concurrency. |
+| Map state | `for` loop / bounded `Promise.all` (e.g. `p-limit`) / step-wrapped `start()` per item for large fan-out | Match the original concurrency mode. |
+| Retry / Catch | `maxRetries`, `RetryableError`, `FatalError`; `try/catch` for compensation | Retry logic moves to step boundaries. |
+| `.waitForTaskToken` | `createHook()` / `createWebhook()` | Hooks for typed signals; webhooks for HTTP. |
+| Child state machine (`StartExecution`) | `"use step"` wrapper around `start()` / `getRun()` | Return the `Run` object for deep-linking. |
+
+A single `Task` state and its Lambda collapse into two directive-tagged functions:
+
+```typescript title="workflows/order.ts"
+export async function processOrder(orderId: string) {
+  'use workflow'; // [!code highlight]
+  const order = await loadOrder(orderId);
+  if (order.total > 1000) await reviewManually(order); // Choice → if
+  await chargePayment(order);
+}
+
+async function loadOrder(id: string) {
+  'use step'; // [!code highlight]
+  return fetch(`https://example.com/api/orders/${id}`).then((r) => r.json());
+}
+```
+
+A `.waitForTaskToken` callback becomes a hook — no SQS queue, task token, or callback Lambda:
+
+```typescript title="workflows/refund.ts"
+import { createHook } from 'workflow';
+
+export async function refundWorkflow(refundId: string) {
+  'use workflow';
+  using approval = createHook<{ approved: boolean }>({
+    token: `refund:${refundId}:approval`, // [!code highlight]
+  });
+  return await approval; // resumed via resumeHook(), not SendTaskSuccess
+}
+```
+
+<Callout type="info">
+Install the migration skill to translate a state machine automatically:
+
+```bash
+npx skills add https://github.com/vercel/workflow --skill migrating-to-workflow-sdk
+```
+</Callout>
+
+### Step Functions features without a direct Workflow SDK equivalent
+
+Each row is a Step Functions capability the Workflow SDK does not replicate one-to-one, paired with how to cover it on the Workflow SDK side:
+
+| Step Functions feature | How to cover it with the Workflow SDK |
+| --- | --- |
+| Express workflows | At-least-once and 5-minute duration fit the durable-replay model poorly; keep them on Step Functions or move to a queue consumer |
+| Distributed Map (up to 10,000 concurrent children, S3 item sources) | Fan out with step-wrapped `start()` per item, then bound concurrency with `p-limit` |
+| Optimized AWS service integrations | Become ordinary SDK calls inside steps; `.sync` waits become explicit polling or hooks |
+| Per-state IAM roles | Steps share the deployment's credentials; scope secrets at deploy time |
+
+---
+*Compiled from public documentation. Step Functions pricing/limits are region-specific (figures are us-east-1); verify against [the AWS pricing page](https://aws.amazon.com/step-functions/pricing/). Not based on head-to-head benchmarks.*

package/docs/comparisons/workflow-sdk-vs-cloudflare-workflows.mdx

@@ -0,0 +1,71 @@
+---
+title: Workflow SDK vs Cloudflare Workflows
+description: How the Workflow SDK compares to Cloudflare Workflows — both are durable replay engines, but they handle versioning, encryption, portability, and global distribution very differently.
+type: conceptual
+summary: Cloudflare Workflows is a durable engine on Workers and Durable Objects. It and the Workflow SDK both replay, but differ on versioning safety, encryption, and lock-in.
+prerequisites:
+  - /docs/foundations/workflows-and-steps
+related:
+  - /docs/how-it-works/event-sourcing
+  - /docs/foundations/streaming
+  - /worlds/building-a-world
+---
+
+[Cloudflare Workflows](https://developers.cloudflare.com/workflows/) is a durable-execution engine built on Cloudflare Workers and SQLite-backed Durable Objects. It's the closest architectural peer to the Workflow SDK — both persist progress and replay to survive failures — which makes the differences in **versioning safety, encryption, and portability** the deciding factors.
+
+<Callout type="info">
+**Choose the Workflow SDK** when you want an open-source, portable engine that runs in your existing app (and off a single vendor), deployment-pinned versioning, and application-level E2E encryption. **Choose Cloudflare Workflows** when you're already all-in on Cloudflare.
+</Callout>
+
+## At a glance
+
+| | Workflow SDK | Cloudflare Workflows |
+| --- | --- | --- |
+| **Category** | Open-source durable-functions SDK; portable backends | Durable execution engine, hosted on Cloudflare |
+| **Durability model** | Event log + deterministic replay | Step-result **memoization** in SQLite-backed Durable Objects + deterministic re-calculation ("game-loop") |
+| **Authoring** | `"use workflow"` / `"use step"` in plain async TS, in your app | Class extends `WorkflowEntrypoint`; explicit `step.do(name, cb)` wrapping; Cloudflare Workers only |
+| **Where it runs** | Your platform (Vercel managed, or self-host) | Cloudflare only — both orchestration and execution run on-network (engine ↔ step over internal RPC) |
+| **Versioning** | Runs pinned to their immutable deployment — safe by default | **No version pinning** — running instances resume on the *latest* deployed code; changing step names/order can desync the cached replay. No patching API |
+| **Encryption** | Per-run AES-256-GCM **end-to-end** encryption | **At-rest only** (AES-256, Cloudflare-managed keys) + TLS; no E2E, no customer-managed keys |
+| **AI & streaming** | `WorkflowAgent` in the AI SDK; native resumable streaming | Durable agents via Workflows + the Agents SDK; resumable streaming buffered in SQLite (mid-call eviction needs opt-in `chatRecovery`) |
+| **Performance** | No-penalty resume; scale-to-zero; up to 100K concurrency (Vercel) | **~0 ms isolate cold starts**; 50K concurrent instances; global Anycast (330+ cities) — strongest cold-start and edge story |
+| **Portability** | Apache-2.0; World abstraction; self-hostable | Engine proprietary; tied to Durable Objects; **highest lock-in** of these tools |
+| **Pricing** | SDK free; pay your platform | Workers Standard: requests + CPU-time + storage + per-step ($0.80 / 100K steps); idle/sleep not billed |
+| **Limits** | 50 MB payloads; 2 GB/run; 10K steps ([Vercel World limits](https://vercel.com/docs/workflows/pricing)) | **1 MiB** step result & event payload; 1 GB state/instance; 10K steps (up to 25K) |
+
+**What the limits mean in practice:** Cloudflare's 1 MiB cap on step results and event payloads is the tightest in this section — a single large model response or document can exceed it, pushing anything sizable into R2/KV indirection — and instance state is capped at 1 GB. The [Vercel World limits](https://vercel.com/docs/workflows/pricing) are 50 MB per payload and 2 GB of state per run.
+
+## Versioning: pinned vs. live code
+
+Both engines replay, so changing code mid-run is the key hazard — and they take opposite approaches:
+
+- **Cloudflare** does not pin a running instance to a code version. When an instance resumes (after a sleep, a wait, or a deploy), it runs against whatever code is currently deployed. Because step names act as the replay cache key, reordering, renaming, or inserting steps before already-completed ones can desync the replay of an in-flight instance. There is no patching API — just the documented "[Rules of Workflows](https://developers.cloudflare.com/workflows/build/rules-of-workflows/)" you must follow by hand.
+- **Workflow SDK** pins each run to the immutable deployment that started it, so a deploy never disturbs in-flight runs. Evolving code is safe by default and upgrades are explicit.
+
+## Encryption and portability
+
+Cloudflare encrypts Durable Object data at rest with Cloudflare-managed keys, but there is no application-level / end-to-end encryption and no customer-managed-key option — payloads are visible to the platform. The Workflow SDK encrypts each run's inputs, outputs, step I/O, and streams with a per-run AES-256-GCM key.
+
+On portability, Cloudflare Workflows is the most locked-in of the tools in this section: the API and Durable-Object-bound state are Cloudflare-specific, so moving means a rewrite. The Workflow SDK is Apache-2.0 and its [World abstraction](/worlds/building-a-world) lets you run the same code on Vercel, on Postgres, or on a backend you build.
+
+## Where Cloudflare leads
+
+Credit where due: Cloudflare's V8-isolate model gives **near-zero cold starts**, and code runs across its global Anycast network with no region selection. For latency-sensitive, globally-distributed workloads on Cloudflare's platform, that's a genuine strength. The Workflow SDK's performance depends on the World it runs on; on Vercel it benefits from Fluid Compute and a 100K concurrency ceiling, with multi-region rolling out.
+
+## Moving from Cloudflare Workflows
+
+There's no automated migration skill for Cloudflare specifically, but the mapping is direct:
+
+| Cloudflare Workflows | Workflow SDK |
+| --- | --- |
+| `class extends WorkflowEntrypoint` + `run(event, step)` | `"use workflow"` function started with `start()` |
+| `step.do(name, cb)` | `"use step"` function called with `await` |
+| `step.sleep` / `step.sleepUntil` | `sleep('1h')` / `sleep(date)` |
+| `step.waitForEvent` | `createHook()` / `createWebhook()` |
+| Per-step `retries` config | `maxRetries`, `RetryableError`, `FatalError` |
+| `env.MY_WORKFLOW.create(...)` binding | `start(workflow, [args])` from your app |
+
+Side effects that lived in `step.do` callbacks move into named `"use step"` functions; the orchestration becomes plain `await` / `if` / `Promise.all` instead of the `WorkflowEntrypoint` class.
+
+---
+*Compiled from public documentation. Verify current Cloudflare Workflows limits and pricing against [developers.cloudflare.com/workflows](https://developers.cloudflare.com/workflows/). Not based on head-to-head benchmarks.*

package/docs/comparisons/workflow-sdk-vs-inngest.mdx

@@ -0,0 +1,102 @@
+---
+title: Workflow SDK vs Inngest
+description: How the Workflow SDK compares to Inngest — event-driven durable functions that run on your own infrastructure over HTTP, with a concept-mapping migration guide.
+type: conceptual
+summary: Inngest is an event-driven durable-functions platform that invokes your code over HTTP and memoizes step results. The Workflow SDK co-locates orchestration and execution and replays from an event log.
+prerequisites:
+  - /docs/foundations/workflows-and-steps
+related:
+  - /docs/foundations/hooks
+  - /docs/foundations/streaming
+  - /docs/ai
+---
+
+[Inngest](https://www.inngest.com) is a durable-functions platform with an **event-driven** core: functions trigger on events or cron, and Inngest invokes your code — running on your own infrastructure — one step at a time over HTTP, memoizing each step's result. It overlaps heavily with the Workflow SDK, with a different execution topology and a strong AI/agent story on both sides.
+
+<Callout type="info">
+**Choose the Workflow SDK** when you want orchestration and execution co-located (no per-step HTTP round-trips), deployment-pinned versioning, and a fully-supported open-source self-host path. **Choose Inngest** when an event-bus model fits your architecture and you want its mature flow-control suite (concurrency, throttling, debounce, batching, priority) out of the box.
+</Callout>
+
+## At a glance
+
+| | Workflow SDK | Inngest |
+| --- | --- | --- |
+| **Category** | Open-source durable-functions SDK | Durable functions on an event-driven platform |
+| **Durability model** | Event log + deterministic replay | **Step-result memoization** (each `step.run` runs once; completed steps are skipped) — not whole-function replay |
+| **Trigger model** | Direct `start(workflow, [args])` (import the function) | Event bus (`inngest.send`) + cron; loosely coupled publishers/consumers |
+| **Where execution runs** | Orchestration + execution co-located on your platform | **Your code runs on your infra**; Inngest invokes it per step over HTTP (Serve) or a persistent worker connection (Connect, in public beta) |
+| **Languages** | TypeScript / JS (Python beta) | TypeScript; Python & Go (production, pre-1.0) |
+| **Versioning** | Runs pinned to immutable deployment | Tracked by step-ID hashes — hot-edit functions, but editing a step's logic under the **same ID** reuses the old memoized result for in-flight runs; rename the ID or route a new function by timestamp for rewrites |
+| **AI & streaming** | `WorkflowAgent` in the AI SDK; native resumable streaming | Native AI SDK via `step.ai.wrap`; **AgentKit** multi-agent framework and durable **Realtime** (`step.realtime.publish`) + `useAgent` hook — both Developer Preview |
+| **Security** | Zero-config per-run E2E encryption by default; platform security is per-World (the Vercel World inherits Vercel's security posture) | Runs on your infra; signed requests; first-party E2E encryption middleware (TS + Python); SOC 2 Type II, HIPAA add-on |
+| **Portability** | Apache-2.0; World abstraction; **self-host supported** | Engine open source (SSPL); self-host via single Go binary + Postgres, but **self-hosting is community/best-effort** — no support SLA, and the `inngest start` binary is Beta (SaaS is the default) |
+| **Pricing** | SDK free; pay your platform | Per-execution: billed for the run **plus each step plus retries**; Pro from $99/mo, then ~$50 per 1M executions |
+| **Limits** | 50 MB payload; 2 GB/run; 10K steps ([Vercel World limits](https://vercel.com/docs/workflows/pricing)) | 1,000 steps/function; 4 MiB step payload; 32 MiB run state; runs up to 366 days |
+
+**What the limits mean in practice:** Inngest's caps are restrictive for real long-running AI workloads. An agent loop spends steps on every model and tool call, so 1,000 steps per function goes quickly; a single large LLM response can approach the 4 MiB step-payload cap; and an accumulated conversation or context easily outgrows 32 MiB of run state. The [Vercel World limits](https://vercel.com/docs/workflows/pricing) are 50 MB per payload and 2 GB of state per run.
+
+## Topology: co-located vs. invoked-over-HTTP
+
+Inngest's engine lives outside your code and calls your functions step-by-step over HTTP (or a Connect worker). That keeps your code on your own infra (a portability and data-locality plus), but adds a network round-trip per step — relevant for workflows with many small sequential steps. The Workflow SDK co-locates orchestration and execution on one platform, so steps don't pay a per-step HTTP hop.
+
+Triggering differs too: Inngest is event-driven (publishers `send` events; functions subscribe), which is great for loosely-coupled fan-out. The Workflow SDK's `start()` imports the workflow function directly — tighter coupling, stronger type safety. For event-bus-style fan-out, wrap `start()` in a shared publisher.
+
+## Versioning
+
+Inngest doesn't use version numbers; it keys state by **step-ID hash**, so you can edit functions while runs are in flight. The catch: if you change the logic *inside* a step but keep the same ID, in-flight runs that already completed that step silently reuse the **old** memoized result — only new runs see the change. To force re-execution you rename the step ID, and for incompatible rewrites the recommended pattern is a new function with timestamp-based event routing.
+
+The Workflow SDK pins each run to its immutable deployment, so in-flight runs always finish on the exact code they started with, and upgrades are explicit — no per-step-ID reasoning required.
+
+## AI agents
+
+Both are strong here. Inngest offers `step.ai.wrap()` (wrap Vercel AI SDK calls as durable steps), **AgentKit** (a multi-agent framework with MCP tools), and durable **Realtime** streaming with a `useAgent` React hook — though AgentKit and Realtime are both Developer Preview. The Workflow SDK offers `WorkflowAgent` directly inside the AI SDK and native [resumable streaming](/docs/ai/resumable-streams). If you're already event-driven and want a batteries-included agent framework, AgentKit is compelling; if you want the agent loop to *be* a durable workflow in your app with streaming built into the runtime, the Workflow SDK fits.
+
+## Migrating from Inngest
+
+| Inngest | Workflow SDK | Note |
+| --- | --- | --- |
+| `inngest.createFunction()` | `"use workflow"` function started with `start()` | No factory or event binding. |
+| `step.run()` | `"use step"` function | Named async function with Node.js access. |
+| `step.sleep()` / `step.sleepUntil()` | `sleep('5m')` / `sleep(date)` | Import from `workflow`. |
+| `step.waitForEvent()` | `createHook()` / `createWebhook()` | Token encodes the routing; no event schema. |
+| `step.invoke()` | `"use step"` wrappers around `start()` / `getRun()` | Spawn a child run. |
+| `inngest.send()` / event triggers | `start()` from your app boundary | Start workflows directly. |
+| Retry config (`retries`) | `maxRetries`, `RetryableError`, `FatalError` | Retries live at the step boundary. |
+| `step.realtime.publish()` / Realtime | `getWritable()` / named streams | Clients read from the stream. |
+
+The `createFunction` factory collapses into a plain exported function:
+
+```typescript title="workflows/order.ts"
+export async function processOrder(orderId: string) {
+  'use workflow'; // [!code highlight]
+  const order = await loadOrder(orderId);
+  return { orderId: order.id, status: 'completed' };
+}
+
+async function loadOrder(orderId: string) {
+  'use step'; // [!code highlight]
+  const res = await fetch(`https://example.com/api/orders/${orderId}`);
+  return res.json() as Promise<{ id: string }>;
+}
+```
+
+<Callout type="info">
+Install the migration skill to translate an Inngest app automatically:
+
+```bash
+npx skills add https://github.com/vercel/workflow --skill migrating-to-workflow-sdk
+```
+</Callout>
+
+### Inngest features without a direct Workflow SDK equivalent
+
+Each row is an Inngest capability the Workflow SDK does not replicate one-to-one, paired with how to cover it on the Workflow SDK side:
+
+| Inngest feature | How to cover it with the Workflow SDK |
+| --- | --- |
+| Flow control (concurrency, throttling, debounce, rate limiting, batching, priority) | No direct function-level analog; enforce limits inside steps or debounce at the publisher before `start()` |
+| Cron / scheduled functions | Trigger from Vercel Cron or a system cron calling `start()` |
+| Event-bus fan-out by name match | Replace with explicit `start()` calls per target workflow |
+
+---
+*Compiled from public documentation. Inngest tier names and pricing vary across sources; verify against [inngest.com/pricing](https://www.inngest.com/pricing). Not based on head-to-head benchmarks.*

package/docs/comparisons/workflow-sdk-vs-temporal.mdx

@@ -0,0 +1,123 @@
+---
+title: Workflow SDK vs Temporal
+description: How the Workflow SDK compares to Temporal — execution model, where workers run, versioning, AI agents, pricing, and a concept-mapping migration guide.
+type: conceptual
+summary: Temporal is a mature, language-agnostic durable-execution platform where you run the workers. The Workflow SDK runs in your existing app and pins runs to immutable deployments.
+prerequisites:
+  - /docs/foundations/workflows-and-steps
+related:
+  - /docs/foundations/hooks
+  - /docs/foundations/streaming
+  - /docs/ai
+  - /worlds/vercel
+---
+
+[Temporal](https://temporal.io) is the most mature durable-execution platform — battle-tested at large scale, with seven language SDKs. It and the Workflow SDK share the same core idea (durable orchestration via event-sourced replay), so the real differences are operational: **where your code runs, how you version it, and how it streams to clients.**
+
+<Callout type="info">
+**Choose the Workflow SDK** when you want durable execution inside your existing TypeScript app with nothing extra to operate, deployment-pinned versioning, and native streaming for AI apps. **Choose Temporal** when you need polyglot SDKs (Go/Java/etc.), want a self-hostable control plane you fully own, or are standardizing a large org on one orchestration backend across many languages.
+</Callout>
+
+## At a glance
+
+| | Workflow SDK | Temporal |
+| --- | --- | --- |
+| **Category** | Open-source durable-functions SDK; managed on Vercel or self-hosted | Durable-execution platform; Temporal Cloud or self-hosted cluster |
+| **Durability model** | Event log + deterministic replay (`"use workflow"` orchestrators, `"use step"` functions) | Event-sourced replay (Workflows + Activities). Same model — `"use workflow"` ≈ Workflow, `"use step"` ≈ Activity |
+| **Languages** | TypeScript / JS (Python beta) | Go, Java, TypeScript, Python, .NET, PHP, Ruby (7 SDKs) |
+| **Where execution runs** | Orchestration + execution + observability co-located on your platform; private networking and E2E encryption out of the box on Vercel | **You run and scale your own Workers.** Temporal Cloud hosts orchestration only; workers connect outbound over the public internet (PrivateLink optional) |
+| **Versioning** | Runs pinned to their immutable deployment — safe by default; opt-in `deploymentId: 'latest'` to upgrade | Editing workflow code can break in-flight runs (non-determinism errors); evolve safely via patch APIs or Worker Versioning (keep old worker fleets draining) |
+| **AI SDK & agents** | `WorkflowAgent` ships in the AI SDK; durable agent loop; **native resumable streaming** (`getWritable`/`getReadable`, `WorkflowChatTransport`) | First-party `@temporalio/ai-sdk` and "Workflow Streams" — both **Public Preview**; streaming rides on Signals/Updates (batched, history-bound) |
+| **Security** | Zero-config per-run AES-256-GCM E2E encryption by default; platform security is per-World (the Vercel World inherits Vercel's security posture) | Workers run your code on your infra (never enters Temporal's plane); client-side E2E via a Codec Server you operate. Cloud: SOC 2 II, HIPAA, GDPR |
+| **Performance** | No-penalty resume; serverless scale-to-zero (true suspension); up to 100K concurrency on Vercel | Self-managed workers are long-running; Cloud namespace default 500 actions/sec (auto-scales) |
+| **Portability** | Apache-2.0 SDK; World abstraction swaps storage/queue/streams independently | MIT server; pluggable persistence (Cassandra/Postgres/MySQL), but an opinionated monolithic backend you run or pay for |
+| **Pricing** | SDK free; pay your platform (Vercel: events + data) or just your infra if self-hosted | Self-host = free software; Temporal Cloud bills per Action (from $50/M) + storage |
+| **Limits** | No run/sleep cap; 10K steps, 50 MB payload, 2 GB/run ([Vercel World limits](https://vercel.com/docs/workflows/pricing)) | No run cap (Continue-As-New for long histories); event history capped at 51,200 events / 50 MB; 2 MB payloads |
+
+**What the limits mean in practice:** Temporal caps payloads at 2 MB and event history at 51,200 events, which binds quickly for AI workloads — a large model context, tool transcript, or embedding batch routinely exceeds 2 MB, forcing external blob storage and claim-check plumbing, and long agent loops must be split with Continue-As-New before the history fills. The [Vercel World limits](https://vercel.com/docs/workflows/pricing) (50 MB payloads, 2 GB of state per run, no run or sleep caps) leave room to keep full contexts in the run itself.
+
+## The biggest difference: what you operate
+
+Temporal Cloud manages the durable engine, but **you still build, deploy, and scale a fleet of Workers** that poll task queues and run your Workflow and Activity code. Those workers connect *out* to Temporal Cloud, typically over the public internet (AWS PrivateLink / GCP Private Service Connect are available as same-region options). Readable observability requires you to stand up a **Codec Server** so the Web UI can decrypt payloads your data converter encrypted.
+
+With the Workflow SDK on Vercel, orchestration, execution, and observability are co-located on one platform with internal networking, and per-run E2E encryption is on by default with no codec server to run. There are no workers, task queues, or a control plane to operate. (Self-hosting via the [Postgres World](/worlds/postgres) is the closest analog to running your own Temporal cluster.)
+
+## Versioning
+
+This is where the two differ most in day-to-day risk. Because both replay code against history, *changing* workflow code mid-flight is the hazard.
+
+- **Temporal:** simply editing a workflow can produce a non-determinism error that breaks or stalls open executions. You evolve safely with **patch APIs** (`patched()` / `GetVersion()`, which accumulate branch cruft) or **Worker Versioning** (Build IDs / Worker Deployments pin workflows to a build and keep the old worker fleet running until it drains). It works, but the burden is on you for every long-running workflow.
+- **Workflow SDK:** runs are **pinned to the immutable deployment that started them**. Shipping new code never touches in-flight runs — they keep replaying against the exact code they began on. Upgrading a run is explicit and opt-in (start it with `deploymentId: 'latest'`, or self-restart at a checkpoint). Safe by default, no patch branches, no draining worker fleets.
+
+## AI agents and streaming
+
+Both target AI agents, but the integration depth differs. The Workflow SDK's `WorkflowAgent` is a first-class construct **inside the AI SDK** (`@ai-sdk/workflow`): the agent loop becomes a durable workflow, each tool `execute` marked `"use step"` is an auto-retried durable step, and partial output streams through [durable, resumable streams](/docs/ai/resumable-streams) that survive reconnects and cold starts.
+
+Temporal ships a first-party `@temporalio/ai-sdk` plugin and a "Workflow Streams" library, but both are **Public Preview**, and streaming is built on Signals/Updates — every chunk is written to history, so it's batched rather than per-token.
+
+## Migrating from Temporal
+
+The model maps closely. Keep your orchestration logic; drop the workers, task queues, and activity modules.
+
+| Temporal | Workflow SDK | Note |
+| --- | --- | --- |
+| Workflow Definition / Execution | `"use workflow"` function started with `start()` | Orchestration stays in the workflow function. |
+| Activity | `"use step"` function | Side effects and Node.js access live in steps. |
+| Worker + Task Queue | Managed execution | No worker fleet or polling loop to operate. |
+| Signal | `createHook()` / `createWebhook()` | Hooks for typed resume signals; webhooks for HTTP callbacks. |
+| Query | `getWritable({ namespace: 'status' })` stream | Stream status durably; clients read the stream instead of polling. |
+| Child Workflow | `"use step"` wrapper around `start()` / `getRun()` | Return the `Run` object so observability can deep-link. |
+| Activity retry policy | `maxRetries`, `RetryableError`, `FatalError` | Retries live at the step boundary. |
+| Event History | Workflow event log / run timeline | Same durable replay; built-in observability UI. |
+
+A minimal translation — the orchestrator loses `proxyActivities` and becomes plain TypeScript:
+
+```typescript title="workflows/order.ts"
+export async function processOrder(orderId: string) {
+  'use workflow'; // [!code highlight]
+  await chargePayment(orderId);
+  return { orderId, status: 'completed' };
+}
+
+async function chargePayment(orderId: string) {
+  'use step'; // [!code highlight]
+  await fetch(`https://example.com/api/orders/${orderId}/charge`, { method: 'POST' });
+}
+```
+
+Signals become hooks — one `createHook()` + `await` replaces a signal definition, handler, and `condition()` guard:
+
+```typescript title="workflows/refund.ts"
+import { createHook } from 'workflow';
+
+export async function refundWorkflow(refundId: string) {
+  'use workflow';
+  using approval = createHook<{ approved: boolean }>({
+    token: `refund:${refundId}:approval`, // [!code highlight]
+  });
+  const { approved } = await approval; // suspends durably until resumed
+  return { refundId, approved };
+}
+```
+
+<Callout type="info">
+Install the migration skill to translate a Temporal app automatically:
+
+```bash
+npx skills add https://github.com/vercel/workflow --skill migrating-to-workflow-sdk
+```
+</Callout>
+
+### Temporal features without a direct Workflow SDK equivalent
+
+Each row is a Temporal capability the Workflow SDK does not replicate one-to-one, paired with how to cover it on the Workflow SDK side:
+
+| Temporal feature | How to cover it with the Workflow SDK |
+| --- | --- |
+| Search attributes / visibility queries | Filter runs by status and timestamps via `getRun()` and the observability UI |
+| Per-activity timeouts (`startToCloseTimeout`, etc.) | Enforce deadlines inside a step with `AbortSignal.timeout(ms)`, or wrap a call in `Promise.race(step(), sleep('5m'))` |
+| Rich retry policy (`backoffCoefficient`, `nonRetryableErrorTypes`) | Only `maxRetries` is configurable; classify with `RetryableError` / `FatalError` and set delay via `new RetryableError(msg, { retryAfter: '5s' })` |
+| Polyglot workers | The Workflow SDK is TypeScript-first (Python in beta); for Go/Java/etc. in the same orchestrator, Temporal remains the better fit |
+
+---
+*Compiled from public documentation. Verify current Temporal pricing, limits, and preview-feature status against [temporal.io/docs](https://docs.temporal.io). Not based on head-to-head benchmarks.*

package/docs/comparisons/workflow-sdk-vs-trigger-dev.mdx

@@ -0,0 +1,103 @@
+---
+title: Workflow SDK vs trigger.dev
+description: How the Workflow SDK compares to trigger.dev — deterministic event-log replay versus CRIU process checkpoint/restore, plus a concept-mapping migration guide.
+type: conceptual
+summary: trigger.dev achieves durability by snapshotting the process (CRIU), so code has no determinism constraints. The Workflow SDK uses event-log replay and runs in your existing app.
+prerequisites:
+  - /docs/foundations/workflows-and-steps
+related:
+  - /docs/foundations/errors-and-retries
+  - /docs/foundations/streaming
+  - /docs/ai
+---
+
+[trigger.dev](https://trigger.dev) is an open-source, TypeScript-first durable task platform. Its defining trait is *how* it achieves durability: instead of replaying code, it **snapshots the whole process** (CRIU checkpoint/restore) at each wait point and restores it later. That single design choice drives most of the differences with the Workflow SDK.
+
+<Callout type="info">
+**Choose the Workflow SDK** when you want durable orchestration that runs in your existing app, a portable open-source backend you can fully self-host, TypeScript *and* Python, and broad framework support. **Choose trigger.dev** when you want a managed task platform with no determinism constraints (code runs as-is), and you're TypeScript-only.
+</Callout>
+
+## At a glance
+
+| | Workflow SDK | trigger.dev |
+| --- | --- | --- |
+| **Category** | Open-source durable-functions SDK that runs in your app | Durable task platform with its own runtime (Cloud or self-hosted) |
+| **Durability model** | Event log + **deterministic replay** (workflow body must be deterministic) | **Process checkpoint/restore (CRIU)** — snapshots memory/CPU/FDs; **no determinism constraints**, code runs as-is |
+| **Authoring** | `"use workflow"` / `"use step"` in your existing app | `task()` / `schemaTask()` deployed to trigger.dev as a separate target (Docker image) |
+| **Languages** | TypeScript / JS (Python beta) | **TypeScript / JS only** |
+| **Where it runs** | Co-located with your app (Vercel managed or self-host) | trigger.dev's run engine (isolated containers) |
+| **Versioning** | Runs pinned to immutable deployment — safe by default | **Atomic versioning** — runs lock to their deploy version; new deploys never touch in-flight runs (same safety property) |
+| **AI & streaming** | `WorkflowAgent` in the AI SDK; native resumable streaming | First-class: AI SDK tools, native `useChat` transport, resumable Realtime, durable multi-turn Sessions, HITL via `wait.forToken` |
+| **Concurrency control** | Enforce in steps / at the publisher | First-class queues + concurrency keys |
+| **Portability** | Apache-2.0; World abstraction; runs anywhere Node runs | Apache-2.0; self-host on Docker/K8s — but CRIU needs a compatible host (heavier than plain Docker); TS-only |
+| **Pricing** | SDK free; pay your platform | Cloud: compute-seconds + per-run ($0.0000338/s Small + $0.000025/run); no charge while checkpointed |
+| **Limits** | 50 MB payload; 2 GB/run; no duration cap ([Vercel World limits](https://vercel.com/docs/workflows/pricing)) | 3 MB payload / 10 MB output; 14-day max run TTL; CPU-time-based max duration |
+
+**What the limits mean in practice:** trigger.dev caps task payloads at 3 MB and outputs at 10 MB — large model contexts and transcripts need external storage — and the 14-day run TTL means human-in-the-loop flows that wait longer than two weeks can't complete in one run. The [Vercel World limits](https://vercel.com/docs/workflows/pricing) are 50 MB payloads, 2 GB of state per run, and no run-duration cap.
+
+## The core difference: checkpoint/restore vs. replay
+
+trigger.dev freezes the entire OS process with CRIU when a task hits a wait point, then restores it later — so there's **no replay and no determinism rule**: you can call `Date.now()` or `Math.random()` anywhere, and prior steps don't re-execute. The cost is an execution model that requires CRIU-capable infrastructure (which makes self-hosting heavier than a plain container) and runs on trigger.dev's runtime as a separate deploy target.
+
+The Workflow SDK reconstructs state by **replaying the workflow function** against its event log. That requires the workflow body to be deterministic (side effects go in `"use step"` functions), but it runs inside your existing app and deployment with no special host requirements, and the [World abstraction](/worlds/building-a-world) lets you swap the storage/queue/stream layers.
+
+Notably, **both pin runs to a version** so deploys never corrupt in-flight work — trigger.dev via atomic version-locking, the Workflow SDK via immutable-deployment pinning.
+
+## AI agents
+
+Both invest heavily in AI. trigger.dev offers AI SDK tool wrapping, a native `useChat` transport over its Realtime layer, resumable streaming, and durable multi-turn Sessions. The Workflow SDK offers `WorkflowAgent` directly inside the AI SDK plus native [resumable streaming](/docs/ai/resumable-streams). Both support human-in-the-loop (trigger.dev's `wait.forToken`, the Workflow SDK's hooks). The deciding factors are usually language (trigger.dev is TS-only; the Workflow SDK adds Python) and whether you want the agent to run in your app vs. on a dedicated platform.
+
+## Migrating from trigger.dev
+
+| trigger.dev | Workflow SDK | Note |
+| --- | --- | --- |
+| `task({ id, run })` | `"use workflow"` function started with `start()` | No factory or id registry. |
+| `schemaTask({ schema, run })` | Typed function + `"use workflow"` | Validate inputs at the call site. |
+| Inline `run` body | `"use step"` functions | Side effects move into named steps. |
+| `wait.for` / `wait.until` | `sleep('5m')` / `sleep(date)` | Import from `workflow`. |
+| `wait.forToken({ timeout })` | `createHook()` + `Promise.race` with `sleep()` | Hooks carry a typed token. |
+| `triggerAndWait()` | `"use step"` wrappers around `start()` / `getRun()` | Spawn + collect. |
+| `batch.triggerAndWait()` | `Promise.all` over collected `Run` handles | Standard concurrency. |
+| `metadata.stream()` / Realtime | `getWritable()` / named streams | Clients read from the stream. |
+| `AbortTaskRunError` | `FatalError` | Stops retries immediately. |
+
+The `task()` factory collapses into a plain function — and because the workflow body is replayed, move side effects into steps:
+
+```typescript title="workflows/order.ts"
+export async function processOrder(orderId: string) {
+  'use workflow'; // [!code highlight]
+  const order = await loadOrder(orderId);
+  return { orderId: order.id, status: 'completed' };
+}
+
+async function loadOrder(orderId: string) {
+  'use step'; // [!code highlight]
+  const res = await fetch(`https://example.com/api/orders/${orderId}`);
+  return res.json() as Promise<{ id: string }>;
+}
+```
+
+<Callout type="warn">
+trigger.dev's `run` body has full Node.js access. The Workflow SDK's `"use workflow"` body runs in a sandboxed VM — side effects (`fetch`, `Date.now()`, `Math.random()`, DB access) must live inside `"use step"` functions. Orchestration stays in the workflow body.
+</Callout>
+
+<Callout type="info">
+Install the migration skill to translate a trigger.dev app automatically:
+
+```bash
+npx skills add https://github.com/vercel/workflow --skill migrating-to-workflow-sdk
+```
+</Callout>
+
+### trigger.dev features without a direct Workflow SDK equivalent
+
+Each row is a trigger.dev capability the Workflow SDK does not replicate one-to-one, paired with how to cover it on the Workflow SDK side:
+
+| trigger.dev feature | How to cover it with the Workflow SDK |
+| --- | --- |
+| Concurrency keys / queue concurrency limits | Enforce limits inside steps or debounce at the publisher |
+| `schedules.task()` / cron | Trigger from Vercel Cron or a system cron calling `start()` |
+| `machine` presets / custom images | Function resources are per-deployment (configured via your hosting platform) |
+
+---
+*Compiled from public documentation. Verify current trigger.dev limits and pricing against [trigger.dev/docs](https://trigger.dev/docs). Not based on head-to-head benchmarks.*

package/docs/configuration/build-and-diagnostics.mdx

@@ -0,0 +1,70 @@
+---
+title: Build and Diagnostics
+description: Build-time environment variables for manifests, source maps, and development diagnostics.
+type: reference
+summary: Configure generated bundles and build-time diagnostics.
+related:
+  - /docs/configuration/framework-options
+  - /docs/api-reference/workflow-next/with-workflow
+---
+
+Build and diagnostics variables are read by the compiler, builders, and framework integrations when your app is built or when the dev server starts.
+
+## Source maps
+
+### `WORKFLOW_SOURCEMAP`
+
+- Framework option: `sourcemap` where supported
+- Default: `inline` in development, `false` in production
+- Controls source maps for generated workflow bundles.
+- Explicit framework config wins over this environment variable.
+
+Accepted values:
+
+- `true`, `inline`, or `1` - append an inline base64 source map to each generated bundle.
+- `linked` - write a `.map` file and add a `sourceMappingURL` comment.
+- `external` - write a `.map` file without adding the comment.
+- `both` - emit inline and external source maps.
+- `false` or `0` - omit source maps.
+
+### `WORKFLOW_EMIT_SOURCEMAPS_FOR_DEBUGGING`
+
+- Default: disabled
+- Legacy source-map toggle kept for compatibility.
+- Only affects the final workflow wrapper and webhook bundle.
+- Prefer `WORKFLOW_SOURCEMAP` or a framework `sourcemap` option.
+
+## Manifests
+
+### `WORKFLOW_PUBLIC_MANIFEST`
+
+- Default: disabled
+- Set `1` to expose the workflow manifest at `/.well-known/workflow/v1/manifest.json`.
+- Useful for e2e tests and tools that need to discover workflows over HTTP.
+
+## Discovery
+
+### `WORKFLOW_DISCOVER_NODE_MODULES`
+
+- Framework option: `discoverWorkflowsInNodeModules` where supported
+- Default: enabled
+- Controls whether workflow discovery descends into `node_modules`. By default, dependencies that declare a `workflow`/`@workflow/*` dependency can ship `"use workflow"`/`"use step"` files that are discovered and compiled into your app's bundles.
+- Set `0` or `false` to opt out — imports from your application code that resolve into `node_modules` are not followed, so the build never reads, scans, or descends into dependency file graphs. This skips the cost of scanning `node_modules` and stops third-party workflow/step/serde code from being discovered. Useful when a dependency ships workflow code you don't want compiled into your app, or trips discovery with directive strings you don't intend to run.
+- The SDK's own runtime serde classes (e.g. `Run`) stay registered — they are reached through a seeded entry point, and imports *within* `node_modules` are still followed.
+- Explicit framework config wins over this environment variable.
+
+## Development diagnostics
+
+### `WORKFLOW_DEV_HMR_LOGS`
+
+- Default: disabled
+- Set `1` to log workflow rebuild activity during `next dev`.
+- Useful for diagnosing watch and HMR issues.
+
+### `WORKFLOW_DEV_WATCH_IGNORED_PATHS`
+
+- Default: unset
+- Dev-mode only (`next dev`). Comma-separated list of path fragments the file watcher should never watch, in addition to the built-in ignores and your project's `.gitignore`.
+- Each entry is matched as a substring of the absolute path (e.g. `/fixtures/,/generated/`).
+- The watcher already respects `.gitignore` (walking from the app directory up to the workspace root). Use this variable only for large directories you cannot or do not want to add to `.gitignore`.
+- Useful when a project has thousands of non-ignored directories and `next dev` fails with `EMFILE: too many open files, watch`.