workflow 5.0.0-beta.35 → 5.0.0-beta.36

package/docs/deploying/world/vercel-world.mdx

@@ -1,270 +0,0 @@
----
-title: Vercel World
-description: Fully-managed world for Vercel deployments with automatic storage, queuing, and authentication.
-type: integration
-summary: Deploy workflows to Vercel with fully-managed storage, queuing, and authentication.
-prerequisites:
-  - /docs/deploying
-related:
-  - /docs/how-it-works/encryption
-  - /docs/deploying/world/local-world
-  - /docs/deploying/world/postgres-world
----
-
-The Vercel World is a fully-managed workflow backend for applications deployed on Vercel. It provides scalable storage, distributed queuing, and automatic authentication with zero configuration.
-
-When you deploy to Vercel, workflows automatically use the Vercel World - no setup required.
-
-## Usage
-
-Deploy your application to Vercel:
-
-```bash
-vercel deploy
-```
-
-That's it. Vercel automatically:
-
-- Selects the Vercel World backend
-- Configures authentication using OIDC tokens
-- Provisions storage and queuing infrastructure
-- Isolates data per environment (production, preview, development)
-
-<FluidComputeCallout />
-
-## Vercel platform documentation
-
-For complete details on pricing, usage limits, and included allotments on Vercel, see the official Vercel documentation:
-
-- **[Vercel Workflow](https://vercel.com/docs/workflows)** — Pricing details, concepts, and observability for Workflow on Vercel
-- **[Vercel limits](https://vercel.com/docs/limits)** — Platform-wide limits including Workflow-specific constraints
-- **[Vercel Hobby plan](https://vercel.com/docs/plans/hobby)** — Free tier included usage for Workflow and other resources
-
-For self-hosted deployments, use the [Postgres World](/worlds/postgres). For local development, use the [Local World](/worlds/local).
-
-## Multi-region
-
-The Vercel World runs in every [Vercel Function region](https://vercel.com/docs/regions). Each workflow run is pinned to a single region at creation time: its stored state, queue dispatch, and streams are all served from that region — no cross-region round trips on the hot path. When your application is deployed in the run's region (the automatic case below), step execution is region-local too.
-
-<Callout type="info">
-  Multi-region requires `workflow` version **5.0.0-beta.33** or later.
-  The 4.x release line does not support region pinning — runs created by
-  4.x always live in `iad1`.
-</Callout>
-
-### Automatic region pinning
-
-No configuration is needed. A run is pinned to the region of the function that creates it:
-
-- Deploy your app to a single region (via [`regions`](https://vercel.com/docs/project-configuration/vercel-json#regions) in `vercel.json` or the project settings), and every run lives there.
-- Deploy to multiple regions for a globally distributed audience, and each run is pinned to the region that served the user who triggered it — workflow data and streaming stay close to that user.
-
-### Explicit region selection
-
-To pin a specific run somewhere else, pass the `region` option to [`start()`](/docs/api-reference/workflow-api/start):
-
-```typescript
-import { start } from "workflow/api";
-import { myWorkflow } from "@/workflows/my-workflow";
-
-const run = await start(myWorkflow, [input], { region: "sfo1" });
-```
-
-<Callout type="warn">
-  The `region` option controls where the run's **data is stored** and where
-  its **queue messages are dispatched from** — it does not deploy your code
-  there. Your workflow and step functions execute in the regions your
-  application is deployed to. For execution to actually happen in the
-  specified region, your app must be deployed there — via
-  [`regions`](https://vercel.com/docs/project-configuration/vercel-json#regions) in
-  `vercel.json` or the Function Regions setting in your project settings.
-  If it isn't, the run's data lives in the requested region but its steps
-  execute in the nearest region your app is deployed to.
-</Callout>
-
-### Good to know
-
-- Reads, hook resumes, and stream consumers can come from anywhere — the platform routes them to the run's region automatically.
-- Runs created by 4.x SDKs (and any runs that existed before you upgraded) live in `iad1` and are unaffected by an upgrade; there is no migration.
-- **Hook tokens are currently stored in `iad1`** for every run, regardless of the run's region: the token-to-run mapping that powers [`getHookByToken()`](/docs/api-reference/workflow-api/get-hook-by-token) and [`resumeHook()`](/docs/api-reference/workflow-api/resume-hook) lives there so tokens — which carry no region information — can always be resolved. Hook *payloads* are not affected: a received payload is recorded on the run's event log, which lives in the run's region like all other run data. This token placement may become a project-level setting in the future.
-
-## Limitations
-
-- **No run migration** - A run's region is fixed at creation. Existing runs cannot be moved to a different region.
-
-## Observability
-
-Workflow observability is built into the Vercel dashboard on your project page. It respects your existing authentication and project permission settings.
-
-The `workflow` CLI commands open a browser window deeplinked to the Vercel dashboard:
-
-```bash
-# List workflow runs (opens Vercel dashboard)
-npx workflow inspect runs --backend vercel
-
-# Launch the web UI (opens Vercel dashboard)
-npx workflow web --backend vercel
-```
-
-The CLI automatically retrieves authentication from the Vercel CLI (`vercel login`) and infers project/team IDs from your local Vercel project linking.
-
-To use the local observability UI instead of the Vercel dashboard:
-
-```bash
-npx workflow web --backend vercel --localUi
-```
-
-To override the automatic configuration:
-
-```bash
-npx workflow inspect runs \
-  --backend vercel \
-  --env production \
-  --project my-project \
-  --team my-team \
-  --authToken <your-token>
-```
-
-Learn more in the [Observability](/docs/observability) documentation.
-
-## Testing & Compatibility
-
-<WorldTestingPerformance worldId="vercel" />
-
-## Configuration
-
-In a Vercel deployment, you do not configure the Vercel World yourself. The platform injects everything the runtime needs, including `VERCEL_DEPLOYMENT_ID`, `VERCEL_PROJECT_ID`, per-request OIDC tokens, and `VERCEL_DEPLOYMENT_KEY` for encryption.
-
-Do not set those platform-provided values yourself.
-
-Most users never need to set the `WORKFLOW_VERCEL_*` variables below. They are only overrides for tools running outside Vercel, such as your laptop or CI, when those tools need to inspect or test a remote Vercel Workflow project and cannot infer the project, team, token, or target environment automatically.
-
-For example, you might set them when running `workflow inspect runs --backend vercel` from CI without an interactive `vercel login`, or when running tests against a specific preview deployment. In normal local development, the CLI infers these values from your `.vercel` directory and Vercel CLI login. In a deployed Vercel function, these variables have no effect on runtime configuration, and the runtime warns if they are set there.
-
-### `WORKFLOW_VERCEL_ENV`
-
-The Vercel environment to target. Options: `production`, `preview`. Default: `production`.
-
-### `WORKFLOW_VERCEL_AUTH_TOKEN`
-
-Vercel API authentication token (secret — keep it in your environment, not in code). Falls back to `VERCEL_TOKEN`, then to your Vercel CLI login.
-
-### `WORKFLOW_VERCEL_PROJECT`
-
-Vercel project ID (`prj_...`).
-
-### `WORKFLOW_VERCEL_PROJECT_NAME`
-
-Vercel project name/slug, used for dashboard links.
-
-### `WORKFLOW_VERCEL_TEAM`
-
-Vercel team ID.
-
-### `WORKFLOW_VERCEL_BACKEND_URL`
-
-Custom base URL for the Vercel workflow API proxy. Default: `https://api.vercel.com/v1/workflow`.
-
-### `VERCEL_WORKFLOW_SERVER_URL`
-
-Custom workflow-server URL for direct runtime requests, or for the proxy to forward to via `WORKFLOW_VERCEL_BACKEND_URL`. Default: unset; normal deployments should not need this.
-
-### `WORKFLOW_SEQUENTIAL_REPLAYS`
-
-Set `WORKFLOW_SEQUENTIAL_REPLAYS=1` to guarantee that **at most one orchestrator (flow) invocation runs at a time per workflow run**. This behavior is off by default; without it, the runtime relies on idempotency and the event log to tolerate concurrent flow invocations of the same run.
-
-When enabled, each run's orchestrator messages are given their own queue topic and the flow trigger is configured with `maxConcurrency: 1`, so [Vercel Queues](https://vercel.com/docs/queues) processes replays for a given run strictly one at a time. Step executions (which ride the flow topic in the combined handler model) get a per-step topic, so steps keep full parallelism.
-
-<Callout type="warn">
-  This variable is read at **both build time and runtime**, so it must be set as a project-level environment variable that applies to your build and your deployed functions. Setting it for only one will produce an inconsistent configuration. The same applies to framework integrations that write their own queue trigger configuration instead of using `getWorkflowQueueTrigger()` from `@workflow/builders`: they only get the runtime half (per-run topics) unless they also emit `maxConcurrency: 1` on their flow trigger.
-</Callout>
-
-Because it routes each run's flow invocations through a dedicated `maxConcurrency: 1` queue topic, enabling this might lead to higher queue performance overhead.
-
-### `VERCEL_QUEUE_MAX_DELAY_SECONDS`
-
-Maximum delay, in seconds, that Workflow uses for one Vercel Queues continuation message when implementing `sleep()`. If a workflow sleeps longer than this, the runtime schedules another continuation message when the first one fires, repeating until the sleep's target time is reached. Default: `82800` (23 hours).
-
-Vercel Queues can delay messages for up to 7 days, capped by the message TTL. Because the default TTL is 24 hours, Workflow uses a 23-hour continuation hop to stay safely inside that default.
-
-### `WORKFLOW_REQUEST_TIMEOUT_MS`
-
-Per-request timeout, in milliseconds, for Vercel World HTTP calls to workflow-server. Default: `60000`. Minimum: `1`.
-
-### `WORKFLOW_MAX_CHUNKS_PER_REQUEST`
-
-Maximum stream chunks written in one Vercel World request. Larger batches are split across multiple requests. Default: `1000`. Minimum: `1`.
-
-### Programmatic configuration
-
-`createWorld()` accepts explicit API configuration. It does not read `WORKFLOW_VERCEL_*` automatically, so pass the environment values yourself when you want a configured World module:
-
-{/*@skip-typecheck: incomplete code sample*/}
-
-```typescript title="my-world.ts" lineNumbers
-import { createWorld } from "@workflow/world-vercel";
-
-export default createWorld({
-  token: process.env.WORKFLOW_VERCEL_AUTH_TOKEN,
-  projectConfig: {
-    projectId: "prj_...",
-    teamId: "team_...",
-    environment: "production",
-  },
-});
-```
-
-```bash title=".env"
-WORKFLOW_TARGET_WORLD="./my-world.ts"
-```
-
-## Versioning
-
-On Vercel, workflow runs are pegged to the deployment that started them. This means:
-
-- Existing workflow runs continue executing on their original deployment, even as new code is deployed
-- New workflow runs start on the latest deployment
-- Code changes won't break in-flight workflows
-
-This ensures long-running workflows complete reliably without being affected by subsequent deployments.
-
-For the full model, including rerunning on latest and explicit upgrade boundaries, see [Versioning](/docs/foundations/versioning).
-
-## Security
-
-### Consumer function security
-
-Workflow handler functions on Vercel are not accessible through public endpoints. During the build step, the Workflow SDK registers each handler as only reachable by [Vercel Queue](https://vercel.com/docs/queues), by using the `experimentalTriggers` configuration in `.vc-config.json`:
-
-```json title=".vc-config.json (step handler)"
-{
-  "experimentalTriggers": [
-    {
-      "type": "queue/v2beta",
-      "topic": "__wkf_step_*",
-      "consumer": "default",
-    }
-  ]
-}
-```
-
-Practically, this means:
-
-- You don't need to add authentication or authorization logic to workflow handlers
-- Unauthorized requests can never reach the step or workflow functions
-- Only messages delivered through Vercel Queues can trigger execution
-- Handlers receive only a message ID that must be retrieved from Vercel's backend, making it impossible to craft custom payloads
-
-<Callout>
-  This configuration is managed entirely by the Workflow SDK build step. You should not need to write this yourself. If you are writing a custom integration, see [Framework Integrations — Security](/docs/how-it-works/framework-integrations#security) for more details.
-</Callout>
-
-## How It Works
-
-The Vercel World uses Vercel's infrastructure for workflow execution:
-
-- **Storage** - Workflow data is stored in Vercel's cloud with automatic replication and [end-to-end encryption](/docs/how-it-works/encryption)
-- **Queuing** - Steps are distributed across serverless functions via [Vercel Queues](https://vercel.com/docs/queues) with automatic retries and [consumer function security](#consumer-function-security)
-- **Authentication** - OIDC tokens provide secure, automatic authentication
-
-For more details, see the [Vercel Workflow documentation](https://vercel.com/docs/workflows).

package/docs/migration-guides/index.mdx

@@ -1,34 +0,0 @@
----
-title: Migration Guides
-description: Move your existing durable workflow system to the Workflow SDK with side-by-side code comparisons and a realistic migration example.
-type: overview
-summary: Migrate from Temporal, Inngest, AWS Step Functions, or trigger.dev to the Workflow SDK.
-related:
-  - /docs/foundations/workflows-and-steps
-  - /docs/getting-started
----
-
-<Callout type="info">
-Install the Workflow SDK migration skill:
-
-```bash
-npx skills add https://github.com/vercel/workflow --skill migrating-to-workflow-sdk
-```
-</Callout>
-
-Move an existing orchestration system to the Workflow SDK. Each guide pairs a concept-mapping table with side-by-side code, so you can translate one piece of your codebase at a time.
-
-<Cards>
-    <Card href="/docs/migration-guides/migrating-from-temporal" title="Migrating from Temporal">
-        Map Activities, Workers, Signals, and Child Workflows onto workflows, steps, hooks, and `start()` / `getRun()`.
-    </Card>
-    <Card href="/docs/migration-guides/migrating-from-inngest" title="Migrating from Inngest">
-        Map `createFunction`, `step.run`, `step.sleep`, `step.waitForEvent`, and `step.invoke` onto workflows, steps, and hooks.
-    </Card>
-    <Card href="/docs/migration-guides/migrating-from-aws-step-functions" title="Migrating from AWS Step Functions">
-        Replace ASL JSON states, Task / Choice / Wait / Parallel states, and `.waitForTaskToken` callbacks with TypeScript.
-    </Card>
-    <Card href="/docs/migration-guides/migrating-from-trigger-dev" title="Migrating from trigger.dev">
-        Map `task()`, `schemaTask()`, `wait.for` / `wait.forToken`, `triggerAndWait`, and `metadata.stream` onto workflows, steps, hooks, and `start()` / `getRun()`.
-    </Card>
-</Cards>

package/docs/migration-guides/meta.json

@@ -1,9 +0,0 @@
-{
-  "title": "Migration Guides",
-  "pages": [
-    "migrating-from-temporal",
-    "migrating-from-inngest",
-    "migrating-from-aws-step-functions",
-    "migrating-from-trigger-dev"
-  ]
-}

package/docs/migration-guides/migrating-from-aws-step-functions.mdx

@@ -1,362 +0,0 @@
----
-title: Migrating from AWS Step Functions
-description: Move an AWS Step Functions state machine to the Workflow SDK by replacing JSON state definitions, Task states, Choice/Wait/Parallel states, Retry/Catch blocks, and .waitForTaskToken callbacks with Workflows, Steps, Hooks, and idiomatic TypeScript control flow.
-type: guide
-summary: Translate an AWS Step Functions state machine into the Workflow SDK with side-by-side code examples.
-prerequisites:
-  - /docs/getting-started/next
-  - /docs/foundations/workflows-and-steps
-related:
-  - /docs/foundations/starting-workflows
-  - /docs/foundations/errors-and-retries
-  - /docs/foundations/hooks
-  - /docs/foundations/streaming
-  - /docs/deploying/world/vercel-world
----
-
-<CopyPrompt
-  text="Replace this AWS Step Functions state machine with Workflow SDK. Run `npm i workflow`. Translate the ASL state machine into an exported async TypeScript function with `&quot;use workflow&quot;`. Move each Lambda/Task side effect into a helper function with `&quot;use step&quot;`. Replace Wait states with `sleep()` from `workflow`. Replace callback tokens with `defineHook()` plus `resumeHook()` from `workflow/api`, or `createWebhook()` for HTTP callbacks. Replace Parallel and Map states with `Promise.all`, bounded batching, or child workflow runs started with `start()`. Replace Retry/Catch rules with normal errors, `RetryableError`, and `FatalError`. Add an API route or server function that starts the workflow with `start(workflowFn, args)` and verify it against the previous state machine behavior."
-/>
-
-Move an AWS Step Functions state machine to the Workflow SDK by replacing JSON state definitions with TypeScript functions. This guide shows the direct mapping between ASL states and Workflow SDK primitives.
-
-<Callout type="info">
-Install the Workflow SDK migration skill:
-
-```bash
-npx skills add https://github.com/vercel/workflow --skill migrating-to-workflow-sdk
-```
-</Callout>
-
-## Why migrate to the Workflow SDK
-
-- Orchestration code is TypeScript, not JSON ASL. Transitions are `await`, branches are `if`/`switch`, and parallelism is `Promise.all`.
-- Streaming is built in. Write durable progress from steps with `getWritable()` and named streams. No DynamoDB or SNS glue to surface status to clients.
-- Infrastructure lives in one deployment. No separate state machine, per-task Lambda, IAM role wiring, or callback SQS queues.
-- Error handling is TypeScript-native: step-level retries, `RetryableError`, and `FatalError` replace per-state Retry/Catch blocks.
-- The `npx workflow` CLI and `npx workflow web` observability UI ship out of the box.
-- AI/agent helpers — `@workflow/ai` for AI-SDK integration and the Claude migration skill — are available as separate installs.
-
-## Before you migrate
-
-This guide assumes **Standard** workflows. Express workflows have different semantics (at-least-once, 5-minute max duration, no execution history) and may need a different target — consider keeping them on Step Functions, moving them to a queue consumer, or ensuring your steps are idempotent before replaying the pattern here.
-
-## What changes when you leave Step Functions?
-
-AWS Step Functions defines workflows as JSON state machines using Amazon States Language (ASL). Each state (Task, Choice, Wait, Parallel, Map) is a node in a declarative graph. Lambda functions handle tasks, Retry/Catch blocks configure per-state error handling, and `.waitForTaskToken` manages callbacks.
-
-The Workflow SDK replaces that JSON DSL with TypeScript. `"use workflow"` functions orchestrate `"use step"` functions in the same file. Branching is `if`/`else`. Waiting is `sleep()`. Parallelism is `Promise.all()`. Retries move down to the step level.
-
-The migration replaces declarative configuration with idiomatic TypeScript and collapses the orchestrator and compute split. Business logic stays the same.
-
-## Concept mapping
-
-| AWS Step Functions | Workflow SDK | Migration 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 TypeScript control flow. |
-| Wait state | `sleep()` | Import `sleep` from `workflow`. |
-| Parallel state | `Promise.all()` | Standard concurrency primitives. |
-| Map state | Inline sequential → `for` loop; bounded parallel (`MaxConcurrency: N`) → batched `Promise.all` or a concurrency limiter like `p-limit`; Distributed Map / large fan-out → `start()` per item, then step-wrapped `getRun()` to collect. | Match the concurrency mode of the original Map. |
-| Retry / Catch | Step retries, `RetryableError`, `FatalError` | Retry logic moves to step boundaries. |
-| `Catch` to a compensation state | `try`/`catch` in the workflow function, calling compensation steps in reverse order (push/pop a rollback stack) | See [`/docs/foundations/errors-and-retries`](/docs/foundations/errors-and-retries) for the SAGA pattern. |
-| `.waitForTaskToken` | `createHook()` or `createWebhook()` | Hooks for typed signals; webhooks for HTTP. |
-| Child state machine (`StartExecution`) | `start()` plus a `"use step"` wrapper around `getRun()` | Return the `Run` object, await its result from another step. |
-| Execution event history | Workflow event log | Same durable replay model. |
-| Progress via DynamoDB / SNS for client polling | `getWritable()` + named streams | Stream durable updates; clients read from the stream. |
-
-<Callout type="info">
-`.waitForTaskToken` becomes `createHook()` or `createWebhook()`. Choice states become `if`/`else`. Map states become `Promise.all()`. Retry policies move from per-state configuration to step-level defaults.
-</Callout>
-
-## Translate your first workflow
-
-Start with a single Task state. In ASL, even "call one Lambda" requires a state machine shell:
-
-```json title="stateMachine.asl.json (Step Functions)"
-"LoadOrder": {
-  "Type": "Task",
-  "Resource": "arn:aws:states:::lambda:invoke",
-  "Parameters": { "FunctionName": "loadOrder", "Payload.$": "$" },
-  "End": true
-}
-```
-
-<Callout type="info">
-Examples use JSONPath mode. If your state machine sets `QueryLanguage: 'JSONata'`, the shape of `Arguments`/`Output` fields differs but the TypeScript translation is identical.
-</Callout>
-
-```typescript title="workflow/workflows/order.ts (Workflow SDK)"
-export async function processOrder(orderId: string) {
-  'use workflow'; // [!code highlight]
-  return await loadOrder(orderId);
-}
-
-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 }>;
-}
-```
-
-What changed: the ASL state machine and its Lambda collapse into two directive-tagged functions in one file.
-
-### Adding a second step
-
-In ASL, a second Task means a new state and a `"Next"` transition. In the Workflow SDK, it's another `await`:
-
-```typescript
-export async function processOrder(orderId: string) {
-  'use workflow';
-  const order = await loadOrder(orderId);
-  await reserveInventory(order.id); // [!code highlight]
-  return { orderId: order.id, status: 'reserved' };
-}
-```
-
-`await` replaces `"Next"`. Each new step is a new function with `"use step"`; no additional deployment. The second version also reshapes the return value; the workflow return type can be anything serializable.
-
-### Starting from an API route
-
-Step Functions starts a run via `StartExecution` (AWS SDK or API Gateway integration). The Workflow SDK starts a run with `start()` from a route handler:
-
-```typescript title="app/api/orders/route.ts"
-import { start } from 'workflow/api';
-import { processOrder } from '@/workflows/order';
-
-export async function POST(request: Request) {
-  const { orderId } = (await request.json()) as { orderId: string };
-  const run = await start(processOrder, [orderId]); // [!code highlight]
-  return Response.json({ runId: run.runId });
-}
-```
-
-### Waiting for a fixed duration
-
-A `Wait` state becomes `sleep()`:
-
-```json title="stateMachine.asl.json (Step Functions)"
-{ "Type": "Wait", "Seconds": 60, "Next": "Next" }
-```
-
-{/* @skip-typecheck: one-line snippet fragment */}
-
-```typescript title="workflow/workflows/order.ts (Workflow SDK)"
-await sleep('1m');
-```
-
-## Wait for an external signal
-
-The minimal ASL for a callback is a Task with `.waitForTaskToken`:
-
-```json title="approval.asl.json (Step Functions)"
-"WaitForApproval": {
-  "Type": "Task",
-  "Resource": "arn:aws:states:::sqs:sendMessage.waitForTaskToken",
-  "Parameters": {
-    "QueueUrl": "https://sqs.us-east-1.amazonaws.com/123456789012/approvals",
-    "MessageBody": {
-      "refundId.$": "$.refundId",
-      "TaskToken.$": "$$.Task.Token"
-    }
-  },
-  "End": true
-}
-```
-
-```typescript title="workflow/workflows/refund.ts (Workflow SDK)"
-import { createHook } from 'workflow';
-
-export async function refundWorkflow(refundId: string) {
-  'use workflow';
-  using approval = createHook<{ approved: boolean }>({ // [!code highlight]
-    token: `refund:${refundId}:approval`,
-  });
-  return await approval;
-}
-```
-
-What changed: no SQS queue, no task token, no callback Lambda. The hook suspends the workflow durably until it is resumed.
-
-### Resuming the hook
-
-Step Functions resumes by calling `SendTaskSuccess` with the task token. The Workflow SDK resumes by calling `resumeHook` with the hook's token:
-
-```typescript title="app/api/refunds/[refundId]/approve/route.ts"
-import { resumeHook } from 'workflow/api';
-
-export async function POST(req: Request, { params }: { params: Promise<{ refundId: string }> }) {
-  const { refundId } = await params;
-  const { approved } = (await req.json()) as { approved: boolean };
-  await resumeHook(`refund:${refundId}:approval`, { approved }); // [!code highlight]
-  return Response.json({ ok: true });
-}
-```
-
-### Branching on the result
-
-In ASL, branching after the wait requires a Choice state. In TypeScript, it's just `if`/`else`:
-
-```json title="approval.asl.json (Step Functions)"
-"CheckApproval": {
-  "Type": "Choice",
-  "Choices": [
-    { "Variable": "$.approved", "BooleanEquals": true, "Next": "Approved" }
-  ],
-  "Default": "Rejected"
-}
-```
-
-{/* @skip-typecheck: continuation snippet */}
-```typescript title="workflow/workflows/refund.ts (Workflow SDK)"
-const { approved } = await approval;
-if (approved) return { refundId, status: 'approved' }; // [!code highlight]
-return { refundId, status: 'rejected' };
-```
-
-## Spawn a child workflow
-
-In ASL, a parent machine calls `StartExecution` (usually via `.sync` or `.waitForTaskToken`) to launch a child. In v5, call `start()` directly from the workflow to launch a child. Wrap `getRun()` and `returnValue` access in a `"use step"` function when you need to await the child result.
-
-### Parent starts a child
-
-```typescript title="workflow/workflows/parent.ts"
-import { start } from 'workflow/api';
-
-export async function parentWorkflow(item: string) {
-  'use workflow';
-  const run = await start(childWorkflow, [item]); // [!code highlight]
-  return { childRunId: run.runId };
-}
-```
-
-### Awaiting the child's result
-
-Add a second step that wraps `getRun()` and awaits `returnValue`:
-
-```typescript
-import { getRun } from 'workflow/api';
-
-async function collectResult(runId: string) {
-  'use step'; // [!code highlight]
-  const run = getRun(runId);
-  return (await run.returnValue) as { item: string; result: string };
-}
-```
-
-Then in the workflow: `const result = await collectResult(run.runId);`. The child workflow itself (`childWorkflow`) is defined elsewhere with `"use workflow"`.
-
-## What you stop operating
-
-Moving off Step Functions removes these surfaces from the application:
-
-- ASL state machine JSON and its reference syntax.
-- Per-task Lambda functions, their IAM roles, and CloudFormation/CDK wiring.
-- Task-token delivery infrastructure (SQS queues, callback Lambdas).
-- Separate progress channels (DynamoDB, SNS) for client-visible updates.
-- Remove CloudWatch and X-Ray wiring that was specific to orchestrator state transitions. Keep (or re-wire) any application-level CloudWatch alarms, log retention policies, or X-Ray propagation that the rest of your AWS footprint still depends on. Workflow SDK exports OTEL traces, so existing OTEL-compatible backends can continue to ingest them.
-
-Workflow and step functions live in the same deployment as the application. State transitions are ordinary control flow (`await`, `if`, `Promise.all`, `for`). Progress streaming, retries, and observability are built in.
-
-### What you take on
-
-Steps that previously invoked AWS services via optimized integrations (EventBridge, DynamoDB, Bedrock, ECS.RunTask.sync, etc.) become ordinary SDK calls inside `'use step'` functions. Credentials and retries move into the step, and `.sync`-style waits for long-running jobs become explicit polling loops or hook-based callbacks.
-
-## Step-by-step first migration
-
-Pick one state machine and migrate it end-to-end before touching the rest. The steps below describe the smallest viable path.
-
-### Step 1: Install the Workflow SDK
-
-Add the `workflow` runtime package.
-
-```bash
-pnpm add workflow
-```
-
-### Step 2: Rewrite the state machine as a `"use workflow"` function
-
-Transitions become `await` calls. Control flow (`Choice`, `Wait`, `Parallel`, `Map`) becomes `if`/`switch`, `sleep`, `Promise.all`, and loops.
-
-```ts 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);
-  await chargePayment(order);
-}
-```
-
-### Step 3: Move each Lambda into a step function
-
-Inline the Lambda body into a function with `"use step"` on the first line. Step functions keep full Node.js access, so existing SDK calls work unchanged.
-
-```ts
-async function loadOrder(id: string) {
-  "use step"; // [!code highlight]
-  return fetch(`/api/orders/${id}`).then((r) => r.json());
-}
-```
-
-### Step 4: Replace `.waitForTaskToken` with a hook
-
-Swap the task-token callback Lambda for `createHook()`. Callers `resumeHook(token, payload)` instead of `SendTaskSuccess`.
-
-Move Retry/Catch off per-state configuration and onto step boundaries. Set `maxRetries` as a function property; throw `RetryableError` or `FatalError` to control retry behavior:
-
-```typescript
-async function chargePayment(orderId: string) {
-  "use step";
-  // ...
-}
-chargePayment.maxRetries = 5;
-```
-
-See [`/docs/foundations/errors-and-retries`](/docs/foundations/errors-and-retries) for the full retry and SAGA compensation patterns.
-
-### Step 5: Start runs from an API route
-
-Delete the `StartExecution` call and IAM wiring. Launch runs directly from a route handler:
-
-```ts title="app/api/orders/route.ts"
-import { start } from "workflow/api";
-import { processOrder } from "@/workflows/order";
-
-export async function POST(req: Request) {
-  const { orderId } = await req.json();
-  const run = await start(processOrder, [orderId]);
-  return Response.json({ runId: run.runId });
-}
-```
-
-### Step 6: Retire the Step Functions infrastructure
-
-Delete the ASL JSON, per-task Lambda deployments, IAM roles, and callback queues. Remove CloudWatch and X-Ray wiring that was specific to orchestrator state transitions — keep alarms, log retention, and traces for resources you still depend on. Verify the run in `npx workflow web` before shipping.
-
-## Features without a 1:1 equivalent
-
-- **Express workflows.** At-least-once semantics and 5-minute duration make them a poor fit for the SDK's durable replay model. Consider keeping them on Step Functions or migrating to a queue consumer.
-- **Distributed Map state.** Up to 10,000 concurrent child executions with S3 item sources has no 1:1 analog; fan out with `start()` per item, then `Promise.all` with `p-limit` to bound concurrency.
-- **Optimized AWS service integrations (`arn:aws:states:::dynamodb:*`, `eventbridge:*`, `bedrock:*`, `ecs:runTask.sync`, etc.).** These become regular SDK calls inside `'use step'` functions — credentials, retries, and polling move into the step.
-- **Per-state IAM roles.** ASL lets each state run under its own IAM role. In the SDK, all steps share the deployment's credentials; scope secrets and roles at deployment time.
-- **CloudWatch alarms / X-Ray cross-service traces / CloudWatch Logs retention.** The SDK event log + observability UI replaces orchestrator state transitions, not AWS-wide observability. Keep alarms and traces for other resources.
-- **`JSONata` `QueryLanguage` mode.** Valid at the source; the TS translation is identical regardless of mode.
-
-## Quick-start checklist
-
-- Replace the ASL state machine with a single `"use workflow"` function. Transitions become `await` calls.
-- Convert each Task / Lambda into a `"use step"` function in the same file.
-- Replace Choice states with `if`/`else`/`switch`.
-- Replace Wait states with `sleep()` from `workflow`.
-- Replace Parallel states with `Promise.all()`.
-- Replace Map states based on their concurrency mode: inline sequential → `for` loop; bounded parallel (`MaxConcurrency: N`) → batched `Promise.all` or a concurrency limiter like `p-limit`; Distributed Map / large fan-out → `start()` per item, then step-wrapped `getRun()` to collect.
-- Replace `StartExecution` child machines with direct `start()` calls and a `"use step"` wrapper around `getRun()` when collecting results.
-- Replace `.waitForTaskToken` with `createHook()` (internal callers) or `createWebhook()` (HTTP callers).
-- Move Retry/Catch to step boundaries using `maxRetries`, `RetryableError`, and `FatalError`.
-- Use `getStepMetadata().stepId` as the idempotency key for external side effects.
-- Stream progress from steps with `getWritable()` instead of polling DynamoDB or SNS.
-- Deploy and verify runs end-to-end with built-in observability.
-
----
-*Verified against `workflow@5.0.0-beta.1` and the AWS Step Functions Amazon States Language spec on 2026-04-16.*