Life of a request

Our World: accepting the run#

1. App → SDK

   The route calls start()

   The example validates the request and resolves a generated workflow ID. Direct SDK callers can skip the HTTP layer. Core resolves the World, target deployment and capabilities, then mints the run ID.

2. SDK in the calling Worker

   Prepare arguments and execution policy

   Core records the engine and execution context. If encryption is enabled, it obtains key material and encrypts serialized values. Cross-deployment starts may probe the target first.

3. SDK → store and dispatch

   Persist creation and publish concurrently

   Core launches the creation event and start publication in parallel. Publication passes through the store’s dispatch code; these are not simply two isolated RPC calls. The start message carries enough creation data for recovery.

4. Store → R2 / SQLite → queue shard

   Commit state and durable intent

   Large payloads reach R2 before the referencing event. The store commits event, materialized state and outbox debt in a transaction. Dispatch first touches the shared workflow runner from the store, then hands the message to a queue shard.

5. SDK → app → caller

   Return a handle, not the result

   The example returns 202 and a run ID. Core examines both start outcomes. A retryable creation failure after successful queue admission can be recovered by the consumer. Conversely, a thrown start error does not prove nothing was persisted.

Our World: delivering and running#

1. Queue alarm → workflow runner

   Start a durable delivery

   The queue claims work on its replay lane. Run deliveries serialize per run, not across all runs on the shard. Alarm-created runner stubs prevent enqueue/replay cycles from continually extending the original subrequest chain.

2. Runner → consumer → executor

   Select the release

   The consumer maps the recorded deployment ID through EXECUTOR_ROUTES and calls its script in the dispatch namespace. Without WFP, it executes locally. A fresh request and SDK route do not imply a fresh Workers isolate.

3. SDK ↔ store / run streams

   Reconstruct the workflow

   Core records or reconstructs the running state, reads event pages and restores a usable QuickJS snapshot if present. Workflow decisions run inside the VM. External I/O belongs in step functions outside that VM.

4. Executor → steps / queue shards

   Execute inline or dispatch

   Some steps run inline. Other steps are queued by key across shards and handled through step runners. Concurrent step creations and publishes gather into request-scoped batches, capped at 500 items and two calls in flight.

5. Step → store → replay lane

   Record the result and continue

   The step writes started and completed or failed events. A continuation wakes the run. Eligible pure wakes coalesce behind a successful replay, reducing redundant work without discarding distinct inputs.

6. SDK → store → indexes

   Suspend or finish

   A hook or sleep persists a waiting condition rather than holding an HTTP request open. On completion, the output and terminal state persist. Index pushes make the final state visible to cross-run listings, subject to eventual consistency.

Vercel: the corresponding path#

1. App Function → SDK

   Resolve deployment, region and encryption

   The adapter supplies deployment identity and a region-tagged run ID. Core serializes the arguments and prepares encryption. Deployment resolution and cross-deployment probes happen when needed.

2. Function → Workflow API + Vercel Queues

   Store creation and send the start

   Core concurrently sends run_created to the managed Workflow API and publishes to the workflow’s regional topic. Queue options identify the target deployment. The same resilient-start rules apply.

3. Vercel Queues → flow Function

   Deliver the message

   The queue handler retrieves and leases a platform-delivered message. The combined SDK route handles workflow and queued-step messages; not every step requires its own Function invocation.

4. Core ↔ managed Workflow API

   Execute and record

   The default engine is native Node. QuickJS is available as an opt-in. Event writes can use a per-run WebSocket channel; batch writes and listings remain HTTP. Events use binary frames with CBOR metadata and opaque payload bytes.

5. Core → queue → Function

   Continue until completion

   Core queues continuations as needed and uses recorded step outcomes on replay. Spec 9 adds a per-run concurrency key. Streams and snapshots go through the managed API, whose backend internals are not established by the public client source.

What a response does and does not guarantee#