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

package/docs/configuration/cli-and-web-ui.mdx

@@ -0,0 +1,182 @@
+---
+title: CLI and Web UI
+description: CLI flags and environment variables for inspecting local, Postgres, and Vercel Workflow runs.
+type: reference
+summary: Configure workflow inspect, workflow cancel, workflow web, workflow health, and observability tooling.
+related:
+  - /docs/observability
+  - /docs/configuration/worlds
+---
+
+The `workflow` CLI uses flags first, then environment variables, then defaults or local inference.
+
+Vercel project and auth settings can often be inferred from `.vercel/project.json` and your Vercel CLI login.
+
+## Target backend
+
+### `--backend` / `-b`
+
+- Environment variable: `WORKFLOW_TARGET_WORLD`
+- Default: `local`
+- Backend to inspect: `local`, `vercel`, or a World package.
+
+### `--authToken` / `-a`
+
+- Environment variable: `WORKFLOW_VERCEL_AUTH_TOKEN`
+- Default: Vercel CLI login
+- Vercel token for `--backend vercel`.
+
+### `--project`
+
+- Environment variable: `WORKFLOW_VERCEL_PROJECT`
+- Default: inferred when possible
+- Vercel project ID for `--backend vercel`.
+
+### `--team`
+
+- Environment variable: `WORKFLOW_VERCEL_TEAM`
+- Default: inferred when possible
+- Vercel team ID for `--backend vercel`.
+
+### `WORKFLOW_VERCEL_PROJECT_NAME`
+
+- CLI flag: none
+- Default: inferred when possible
+- Vercel project slug used for dashboard links.
+
+### `--env` / `-e`
+
+- Environment variable: `WORKFLOW_VERCEL_ENV`
+- Default: `production`
+- Vercel environment for `--backend vercel`.
+- Accepts `production` or `preview`.
+
+## Web UI
+
+### `--web` / `-w`
+
+- Environment variable: none
+- Default: disabled
+- Opens the relevant dashboard or web UI instead of printing terminal output.
+
+### `--webPort`
+
+- Environment variable: `WORKFLOW_WEB_PORT`
+- Default: `3456`
+- Port for the local web UI server.
+
+### `--noBrowser`
+
+- Environment variable: `WORKFLOW_DISABLE_BROWSER_OPEN`
+- Default: browser opens
+- Prevents the CLI from opening a browser for web UI commands.
+
+### `--localUi`
+
+- Environment variable: `WORKFLOW_LOCAL_UI`
+- Default: disabled
+- Uses the local web UI instead of the Vercel dashboard when inspecting Vercel.
+
+### `--url`
+
+- Environment variable: none
+- Default: disabled
+- Prints the dashboard or run deep-link URL instead of opening a browser or starting a local server.
+
+## Output and filtering
+
+### `--json` / `-j`
+
+- Environment variable: none
+- Default: disabled
+- Prints machine-readable JSON where the command supports it.
+
+### `--sort`
+
+- Environment variable: none
+- Default: `desc`
+- Sort order for list commands. Accepts `asc` or `desc`.
+
+### `--limit`
+
+- Environment variable: none
+- Default: `20`
+- Number of items returned per page for list commands.
+
+### `--cursor`
+
+- Environment variable: none
+- Default: unset
+- Pagination cursor for list commands.
+
+### `--interactive` / `-i`
+
+- Environment variable: none
+- Default: disabled
+- Enables keyboard-controlled pagination for supported list commands.
+
+## Bulk cancel
+
+`workflow cancel <run-id>` cancels one run. Given a filter instead, it bulk-cancels a batch; bulk mode requires `--status` or `--workflowName`.
+
+### `--status`
+
+- Command: `workflow cancel`
+- Default: unset
+- Restricts the batch to this status. Only `pending` and `running` are accepted — terminal runs cannot be cancelled.
+
+### `--workflowName` / `-n`
+
+- Command: `workflow cancel`
+- Default: unset
+- Restricts the batch to one workflow. Expects the generated workflow ID from `workflow inspect runs`, not the short function name.
+
+### `--limit` (cancel)
+
+- Command: `workflow cancel`
+- Default: `50`
+- Maximum runs to cancel in one batch (1–500). Only one batch is cancelled per invocation; re-run to cancel the next.
+
+### `--confirm` / `-y`
+
+- Command: `workflow cancel`
+- Default: disabled
+- Skips the interactive confirmation prompt.
+
+## Health checks
+
+### `--port` / `-p`
+
+- Command: `workflow health`
+- Environment variable: `WORKFLOW_LOCAL_BASE_URL`, then `PORT`
+- Default: `3000` when neither env var is set
+- Local server port for health checks.
+- The flag writes `WORKFLOW_LOCAL_BASE_URL`.
+
+## Verbose logging and updates
+
+### `--verbose` / `-v`
+
+- Environment variable: `DEBUG`
+- Default: disabled
+- Enables verbose CLI output.
+
+### `WORKFLOW_NO_UPDATE_CHECK`
+
+- CLI flag: none
+- Default: update check enabled
+- Set `1` to disable the CLI update check.
+
+## Observability paths
+
+### `WORKFLOW_OBSERVABILITY_CWD`
+
+- CLI flag: none
+- Default: `process.cwd()`
+- Working directory used by observability tooling to find `.vercel`, `.workflow-data`, and manifests.
+
+### `WORKFLOW_MANIFEST_PATH`
+
+- CLI flag: none
+- Default: inferred
+- Explicit path to the workflow manifest for the web UI.

package/docs/configuration/framework-options.mdx

@@ -0,0 +1,165 @@
+---
+title: Framework Options
+description: Build-time and dev-server configuration for Workflow framework integrations.
+type: reference
+summary: Configure Workflow through framework plugins and module options.
+related:
+  - /docs/api-reference/workflow-next/with-workflow
+  - /docs/configuration/build-and-diagnostics
+---
+
+Framework options are read at build or dev-server startup. Use them for settings that belong in source control, such as source-map behavior or framework-specific output paths.
+
+## Next.js
+
+`withWorkflow()` accepts an optional second argument.
+
+### `workflows.local.port`
+
+- Environment override: `PORT`
+- Default: auto-detected
+- Local-only. Sets the application port used by the Local World when queue messages call back into the app.
+- The option writes `PORT` for non-Vercel builds.
+
+### `workflows.sourcemap`
+
+- Environment override: `WORKFLOW_SOURCEMAP`
+- Default: `inline` in development, `false` in production
+- Controls source maps for generated workflow bundles.
+- Explicit config wins over `WORKFLOW_SOURCEMAP`.
+
+```typescript title="next.config.ts" lineNumbers
+import { withWorkflow } from "workflow/next";
+
+export default withWorkflow(
+  {},
+  {
+    workflows: {
+      local: {
+        port: 4000,
+      },
+      sourcemap: false,
+    },
+  }
+);
+```
+
+## Nitro and Nuxt
+
+Configure Workflow through the Nitro `workflow` module options.
+
+### `workflow.dirs`
+
+- Environment override: none
+- Default: `["workflows"]`
+- Directories scanned for workflow files.
+
+### `workflow.typescriptPlugin`
+
+- Environment override: none
+- Default: `false` for raw Nitro, `true` through the Nuxt module
+- Enables the Workflow TypeScript language-service plugin in generated `tsconfig.json`.
+- This affects editor diagnostics and completions. Workflow builds do not require it.
+- Raw Nitro leaves it opt-in because it changes TypeScript editor behavior. Nuxt enables it by default because the Nuxt module owns the generated `tsconfig.json` flow.
+
+### `workflow.runtime`
+
+- Environment override: none
+- Default: framework default
+- Node.js runtime emitted for Vercel Functions, such as `nodejs22.x` or `nodejs24.x`.
+
+### `workflow.sourcemap`
+
+- Environment override: `WORKFLOW_SOURCEMAP`
+- Default: `inline` in development, `false` in production
+- Controls source maps for generated workflow bundles.
+
+## NestJS
+
+Configure Workflow through `WorkflowModule.forRoot()`.
+
+### `workingDir`
+
+- Environment override: none
+- Default: `process.cwd()`
+- Application root used for workflow discovery and bundling.
+
+### `dirs`
+
+- Environment override: none
+- Default: `["src"]`
+- Directories scanned for workflow files.
+
+### `outDir`
+
+- Environment override: none
+- Default: `.nestjs/workflow`
+- Directory for generated workflow bundles.
+
+### `watch`
+
+- Environment override: none
+- Default: `false`
+- Rebuilds workflow bundles during development.
+
+### `moduleType`
+
+- Environment override: none
+- Default: `es6`
+- Set to `commonjs` when the Nest app compiles TypeScript to CJS through SWC.
+
+### `distDir`
+
+- Environment override: none
+- Default: `dist`
+- Compiled JavaScript output directory used by the CJS import rewrite.
+
+### `sourcemap`
+
+- Environment override: `WORKFLOW_SOURCEMAP`
+- Default: `inline` in development, `false` in production
+- Controls source maps for generated workflow bundles.
+
+### `skipBuild`
+
+- Environment override: none
+- Default: `false`
+- Skips bundle generation when bundles are already pre-built.
+
+## Astro
+
+### `sourcemap`
+
+- Environment override: `WORKFLOW_SOURCEMAP`
+- Default: `inline` in development, `false` in production
+- Controls source maps for generated workflow bundles.
+
+## SvelteKit
+
+### `sourcemap`
+
+- Environment override: `WORKFLOW_SOURCEMAP`
+- Default: `inline` in development, `false` in production
+- Controls source maps for generated workflow bundles.
+
+## Rollup
+
+### `exclude`
+
+- Environment override: none
+- Default: `[]`
+- Path prefixes skipped by the directive transform.
+
+## Source-map values
+
+`WORKFLOW_SOURCEMAP` accepts these 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.
+
+<Callout type="info">
+The legacy `WORKFLOW_EMIT_SOURCEMAPS_FOR_DEBUGGING=1` variable still works, but it only affects the final workflow wrapper and webhook bundle. Prefer `WORKFLOW_SOURCEMAP` or a framework `sourcemap` option.
+</Callout>

package/docs/configuration/index.mdx

@@ -0,0 +1,32 @@
+---
+title: Configuration
+description: Reference for Workflow SDK configuration options, environment variables, and CLI overrides.
+type: conceptual
+summary: Configure framework integrations, Worlds, runtime tuning, builds, and CLI observability.
+prerequisites:
+  - /docs/foundations/workflows-and-steps
+related:
+  - /docs/configuration/framework-options
+  - /docs/configuration/worlds
+  - /docs/configuration/runtime-tuning
+  - /docs/configuration/build-and-diagnostics
+  - /docs/configuration/cli-and-web-ui
+---
+
+Workflow SDK is configured through typed framework options, World factory options, environment variables, and CLI flags.
+
+When more than one surface controls the same setting, the usual precedence is:
+
+```txt
+explicit option or CLI flag > environment variable > built-in default
+```
+
+Invalid environment variable values do not crash the app. They log a warning and fall back to the default, or to the documented clamp range.
+
+## Configuration areas
+
+- [Framework options](/docs/configuration/framework-options) - build-time and dev-server options for Next.js, Nitro, NestJS, Astro, SvelteKit, and Rollup.
+- [Worlds](/docs/configuration/worlds) - `WORKFLOW_TARGET_WORLD`, Local World, Postgres World, and Vercel World configuration.
+- [Runtime tuning](/docs/configuration/runtime-tuning) - replay budgets, inline execution, queue delivery limits, compression, tracing, and advanced runtime escape hatches.
+- [Build and diagnostics](/docs/configuration/build-and-diagnostics) - public manifests, HMR logs, and source-map controls.
+- [CLI and web UI](/docs/configuration/cli-and-web-ui) - `workflow inspect`, `workflow web`, `workflow health`, and observability environment overrides.

package/docs/configuration/meta.json

@@ -0,0 +1,12 @@
+{
+  "title": "Configuration",
+  "pages": [
+    "index",
+    "framework-options",
+    "worlds",
+    "runtime-tuning",
+    "build-and-diagnostics",
+    "cli-and-web-ui"
+  ],
+  "defaultOpen": false
+}

package/docs/configuration/runtime-tuning.mdx

@@ -0,0 +1,276 @@
+---
+title: Runtime Tuning
+description: Runtime environment variables for replay, inline execution, queue delivery, compression, tracing, and advanced limits.
+type: reference
+summary: Tune Workflow runtime behavior where workflows execute.
+related:
+  - /docs/configuration/worlds
+  - /docs/how-it-works/event-sourcing
+---
+
+Runtime variables are read where workflows execute. Set them on the deployment or dev server.
+
+## Client polling
+
+### `WORKFLOW_RETURN_VALUE_POLL_INTERVAL_MS`
+
+- Default: `1000`
+- Minimum: `1`
+- Delay between status requests made by [`Run.returnValue`](/docs/api-reference/workflow-api/get-run) while a workflow run is not yet complete.
+- Increase it to reduce polling traffic at the cost of noticing completion later.
+- This variable is read by the process awaiting `Run.returnValue`, such as an E2E test runner, rather than by the workflow deployment.
+
+## Replay and queue delivery
+
+### `WORKFLOW_REPLAY_TIMEOUT_MS`
+
+- Default: `240000`
+- Clamp: `30000` to `780000`
+- Charged time budget for replay and orchestration work in one handler invocation.
+- Covers loading events, re-running the workflow function, resolving suspensions, and scheduling follow-up work.
+- Does not include time spent inside inline `"use step"` bodies. Steps are bounded by the platform function duration instead.
+
+For example, a workflow can run a 10-minute inline step even with `WORKFLOW_REPLAY_TIMEOUT_MS=300000`, because the replay budget is paused while the step body runs.
+
+### `WORKFLOW_REPLAY_TIMEOUT_MAX_RETRIES`
+
+- Default: `3`
+- Queue deliveries that may hit the replay timeout before the run is failed with `REPLAY_TIMEOUT`.
+
+### `WORKFLOW_MAX_QUEUE_DELIVERIES`
+
+- Default: `48`
+- Delivery attempts before a run or step is failed gracefully.
+- Can only be lowered. The default is calibrated so Workflow can record failure before the queue expires the message.
+
+### `WORKFLOW_REPLAY_DIVERGENCE_MAX_RETRIES`
+
+- Default: `3`
+- Recovery replays before replay divergence is recorded as corruption.
+
+### `WORKFLOW_DISABLE_LAZY_HOOK_RESUME`
+
+- Default: enabled (lazy hook resume on)
+- Resuming a hook persists the `hook_received` event and publishes the workflow invocation concurrently, cutting a round trip off resume latency. On this parallel path the queue message also carries the payload, so a transient event-write failure still resumes the run — the queue consumer re-ensures the `hook_received` event before replay. A backend `(runId, resumeId)` constraint keeps the two writers converging on exactly one event.
+- The runtime falls back to the sequential path automatically when the consumer or backend does not attest dedup support (or the payload is too large to inline on the queue message). On the sequential path the event is written *before* dispatch and its failure fails the resume — the fallback trades that resilience away to stay safe when dedup is not enforced, it does not preserve it.
+- Set `1` to force the sequential path as a kill switch. The chosen strategy is reported on the resume span as `workflow.hook.resume_strategy`.
+
+### `WORKFLOW_DEPLOYMENT_MISMATCH_MAX_RETRIES`
+
+- Default: `3`
+- Times a delivery that reached a deployment other than the one its run is pinned to is re-routed to that deployment before the run is failed with [`DEPLOYMENT_MISMATCH`](/docs/errors/deployment-mismatch).
+- Re-routed deliveries back off exponentially (1s, 2s, 4s). Set to `0` to fail the run on the first misrouted delivery.
+- Only applies to Worlds with atomic, immutable deployments (the Vercel World). A run whose pinned deployment cannot be reached at all fails immediately regardless of this value.
+- Transient or unknown queue publishing failures use normal queue redelivery and do not consume this budget.
+
+### `WORKFLOW_PRECONDITION_GUARD`
+
+- Default: enabled
+- An optimistic-concurrency guard for event creation: replay-context event creations describe the snapshot they replayed from — its latest event timestamp (`stateUpdatedAt`), the number of events it contains (`stateEventCount`), and its event-log cursor (`stateCursor`) — and a backend that supports the guard rejects a creation with 412 ([`PreconditionFailedError`](/docs/api-reference/workflow-errors/precondition-failed-error)) when a newer out-of-band event (a received hook or a completed step) was recorded after that snapshot, or when the snapshot is missing an event recorded at or before it.
+- On rejection the runtime restarts the replay in the same invocation from a corrected event log, and falls back to a re-invocation with a fresh replay once the restart budget is spent. The rejected write is never retried as-is: a replay working from a corrected log derives different events, so only a fresh replay may write again.
+- When enabled — and the World declares that it enforces the guard (`capabilities.preconditionGuard`; the Vercel World does) — the runtime also keeps the per-step event-log delta optimization (consuming the delta returned by a step's terminal write instead of issuing an extra `events.list` per step) active while the run has an open hook. Without an enforced guard, an open hook disables it.
+- While a hook is open on a guard-enforcing deployment, inline steps take the await-then-run path even when optimistic inline start is enabled: the step's `step_started` claim carries the snapshot and is awaited before the body runs, so a claim the backend rejects as stale never executes user code.
+- Backends that do not support the guard ignore the snapshot; they must not declare the capability, so guard-dependent optimizations stay off against them even when the flag is set.
+- The guard only ever rejects on evidence, and it fails open in every other case: a backend that cannot decide — because its record of recent events is incomplete, has expired, or covers only part of the run's history — must accept the write. A rejection therefore always means the snapshot really was incomplete, but the absence of one does not prove it was complete. Busy runs (wide step fan-outs, high hook volume) are the most likely to skip the check.
+- As a result, 412 volume describes a workload rather than the health of a deployment, and a run that never sees one is not evidence the guard is inactive.
+- Set `0` to disable.
+
+### `WORKFLOW_PRECONDITION_MAX_INPROCESS_RESTARTS`
+
+- Default: `3`
+- How many times a single invocation restarts its replay in-process after a rejected event creation before it falls back to a re-invocation.
+- A restart reloads the event log and rebuilds the workflow from scratch, so it costs a replay but no queue round trip. A World may attach the missing events to its rejection, in which case the first restart needs no event-log request at all.
+
+### `WORKFLOW_PRECONDITION_MAX_REINVOCATIONS`
+
+- Default: `5`
+- How many re-invocations one run may spend on rejected event creations before it is failed with `RUNTIME_ERROR`.
+- Counted on the run's queue messages rather than per invocation, because a re-invocation enqueues a fresh message and so restarts the ordinary delivery count. Without this budget a run whose event log keeps growing faster than it can be read would cycle indefinitely.
+
+### `WORKFLOW_PRECONDITION_REINVOKE_DELAY_SECONDS`
+
+- Default: `2`
+- Delay before a re-invocation caused by a rejected event creation.
+- Unlike an in-process restart, which re-reads immediately, a re-invocation only happens once the in-process budget failed to catch up — so the delay gives the other writers a moment to quiesce.
+
+### `WORKFLOW_PER_KIND_CORRELATION_IDS`
+
+- Default: disabled
+- Experimental. Gives each kind of entity a workflow creates — steps, waits, hooks, attribute writes, abort controllers, stream IDs — its own sequence of correlation IDs.
+- With one sequence shared by every kind, an ID is an ordinal over the whole run, so a single extra draw of any kind shifts every ID after it. Two concurrent replays of the same run that disagree about one `sleep()` then assign different IDs to every step that follows, and each writes events the other can neither match nor consume, which fails the run with `CORRUPTED_EVENT_LOG`. Per-kind sequences confine that to the kind that actually differs.
+- IDs remain ordered within a kind, so hooks created by your workflow are still listed in creation order. A hook the runtime creates for you, such as the one backing an abort controller, draws from its own kind and so is listed at an arbitrary position relative to your hooks rather than at its creation position.
+- A run must replay under the scheme that minted its IDs. A replay that switches schemes mid-run assigns IDs its own earlier events do not carry, so it can consume none of them and the run fails.
+  - On Vercel, a run keeps replaying on the deployment it started on, so it only ever sees the value baked into that deployment. Changing the setting affects new runs only.
+  - Elsewhere — `@workflow/world-postgres`, `@workflow/world-local`, any self-hosted process — nothing pins a run to the code that started it. Turn the setting on during a quiet window with no runs in flight, and roll the new value out to your whole fleet at once: a rolling deploy that leaves both values live replays one run under two schemes concurrently, which is the failure the setting exists to reduce.
+- Set `1` to enable.
+
+## Inline execution
+
+### `WORKFLOW_V2_TIMEOUT_MS`
+
+- Default: `120000`
+- Wall-clock guard for the inline replay loop.
+- Once elapsed, the handler requeues the workflow instead of continuing to run more inline work in the same invocation.
+
+### `WORKFLOW_MAX_INLINE_STEPS`
+
+- Default: `3`
+- Clamp: `1` to `16`
+- Number of newly-created steps one invocation runs inline in parallel before queueing the rest.
+
+### `WORKFLOW_TURBO`
+
+- Default: enabled
+- Fast path for a run's first delivery.
+- Stops forcing optimistic inline step start once the run creates a hook or wait.
+- Set `0` or `false` to disable.
+
+### `WORKFLOW_OPTIMISTIC_INLINE_START`
+
+- Default: disabled
+- Starts inline step bodies before their `step_started` event is confirmed.
+- Use only when step side effects are idempotent.
+- Set `0` or `false` to force it off, including the first-delivery fast path used by `WORKFLOW_TURBO`.
+
+### `WORKFLOW_RETAINED_VM`
+
+- Default: enabled
+- Keeps the suspended workflow VM alive across inline steps within one invocation, so each iteration of the inline loop appends only the newly written events instead of replaying the whole event log in a fresh VM.
+- Suspensions involving hooks, waits, or attributes — and any replay divergence — always fall back to a full replay.
+- Step inputs made of plain data (objects, arrays, primitives) and standard built-ins (`Map`, `Set`, `Date`, `RegExp`, typed arrays, `ArrayBuffer`, `URL`, `Headers`) keep the VM retained. Patching or polyfilling built-in prototypes doesn't change that: serialization never calls them. A boundary falls back to a full replay only when serializing its arguments runs code the workflow controls — a getter, a proxy, a custom class serializer — or computes an `Error`'s stack trace.
+- Set `0` or `false` to replay from scratch in a fresh VM on every iteration.
+
+### `WORKFLOW_INLINE_OWNERSHIP`
+
+- Default: enabled
+- Records which queue message owns each inline step execution, so a wake (hook resume, elapsed wait) that replays the run mid-step schedules a delayed backstop instead of immediately re-dispatching — and re-executing — the step. See [Inline step message ownership](/v5/docs/changelog/step-message-ownership).
+- Set `0` or `false` to revert to the previous unconditional immediate re-dispatch.
+
+### `WORKFLOW_INLINE_OWNERSHIP_LEASE_SECONDS`
+
+- Default: `860`
+- Clamp: `1` to `900`
+- How long after an inline step's latest `step_started` other invocations assume its owner may still be executing the body. Within the lease they defer the step's backstop message; past it they enqueue immediately.
+- Raise this on self-hosted multi-instance deployments whose inline steps run longer than the default (the default is sized for Vercel's function duration ceiling).
+
+## Workflow VM engine
+
+### `WORKFLOW_VM`
+
+- Default: `node`
+- Values: `node` or `quickjs`
+- Selects the sandboxed VM engine that executes workflow functions (`"use workflow"`). Step functions are unaffected — they always run with full Node.js access.
+- `node` (default) runs workflow code in a [`node:vm`](https://nodejs.org/api/vm.html) context.
+- `quickjs` (experimental) runs workflow code in a [QuickJS](https://github.com/quickjs-ng/quickjs) VM compiled to WebAssembly (via [`quickjs-wasi`](https://github.com/vercel-labs/quickjs-wasi)). Both engines implement the same event-replay execution model (seeded PRNG, deterministic clock, and correlation-ID sequences are identical), but the **global surface is not identical** — see the differences below before switching an existing deployment. The QuickJS engine is intended for platforms that do not implement `node:vm`, and is the foundation for future VM-memory snapshotting.
+- Global-surface differences under `quickjs` (workflow functions only — step functions always have full Node.js):
+  - `crypto.getRandomValues()` and `crypto.randomUUID()` are provided and deterministic (seeded like the node engine's). All `crypto.subtle.*` methods throw with guidance to move to a step function — including `digest`, which the node engine supports.
+  - `Intl` is not available (QuickJS has no ICU). The `Intl.*` constructors throw, and `toLocaleString`-family methods (including `localeCompare`) throw when called **with an explicit locale** — calling them without arguments keeps the engine default. Perform locale-sensitive formatting in a step function.
+  - `WebAssembly` and `Atomics` are not available.
+  - `process` exposes only a frozen copy of `env`, matching the node engine.
+- The engine choice is stamped into the run's `executionContext` when the run starts, so a run keeps executing on the engine it started on even if the deployment's `WORKFLOW_VM` changes. Runs without a stamped engine use the handler's `WORKFLOW_VM` value.
+- Unknown values throw at startup.
+
+## Compression and tracing
+
+### `WORKFLOW_DISABLE_COMPRESSION`
+
+- Default: compression enabled
+- Set `1` to disable compression when writing payloads.
+- Reads still decompress existing payloads.
+
+### `WORKFLOW_COMPRESSION_CODEC`
+
+- Default: automatic
+- Forces the write-side codec to `zstd` or `gzip`.
+- Invalid values are ignored. Automatic mode prefers `zstd` when the current Node.js runtime supports it, otherwise it falls back to `gzip`.
+
+### `WORKFLOW_TRACE_MODE`
+
+- Default: `linked`
+- OpenTelemetry span topology for runs.
+- Accepts `linked` or `continuous`.
+
+### `DEBUG`
+
+- Default: unset
+- Debug log filter with wildcards and negation.
+- Examples: `workflow:*`, `workflow:*,-workflow:telemetry:*`.
+
+## Transport
+
+### `WORKFLOW_H2_MULTIPLEX`
+
+- Default: enabled
+- On the Vercel World, lets concurrent event-log requests share one HTTP/2 connection instead of one connection per in-flight request.
+- Set `0` to send one event request per connection.
+
+## Queue namespace
+
+### `WORKFLOW_QUEUE_NAMESPACE`
+
+- Default: none
+- Queue topic namespace shared by build output and Worlds.
+- Must match `^[a-z][a-z0-9]*$`.
+- Set it consistently at build and runtime.
+
+## Streams and waits
+
+These variables are primarily for tests, debugging, or unusual deployments.
+
+### `WORKFLOW_STREAM_FLUSH_INTERVAL_MS`
+
+- Default: `0` (dispatch the first chunk of an idle stream immediately)
+- Group-commit window for the *leading* chunk of an idle stream. `0` sends it at once; a positive value holds it up to that many milliseconds to collect a group — an opt-in trade of first-chunk latency for larger batches, useful for slow-but-steady producers. Chunks arriving while a request is already in flight always coalesce into the next group regardless of this setting.
+- Also available as `streamFlushIntervalMs` on Worlds that expose it (the env var, when set, takes precedence over the World option).
+
+### `WORKFLOW_STREAM_MAX_INFLIGHT_CHUNKS`
+
+- Default: `1000`
+- Flow-control bound: how many stream chunks may be read-but-not-yet-durably-written while writes are coalesced. Once this many are outstanding, the producer pauses reading until a batch is written. Bounds in-memory buffering; distinct from the per-request batch caps below.
+
+### `WORKFLOW_STREAM_MAX_CHUNKS_PER_BATCH`
+
+- Default: `1000`
+- Wire limit: maximum number of chunks sent in a single coalesced multi-write. Larger bursts are split across requests so one request can't exceed the server's per-multi-write chunk cap.
+
+### `WORKFLOW_STREAM_MAX_BYTES_PER_BATCH`
+
+- Default: `1048576` (1 MiB)
+- Wire limit: maximum cumulative bytes in a single coalesced multi-write, so large chunks don't produce a request body that platform limits reject. A single chunk larger than this is still sent on its own.
+
+### `WORKFLOW_STREAM_MAX_BUFFERED_BYTES`
+
+- Default: `8388608` (8 MiB)
+- Flow-control bound: maximum cumulative bytes accepted into the stream writer's group-commit buffer before `write()` applies backpressure. The byte-denominated counterpart of `WORKFLOW_STREAM_MAX_INFLIGHT_CHUNKS`; distinct from `WORKFLOW_STREAM_MAX_BYTES_PER_BATCH`, which only splits how much goes out in one request.
+
+### `WORKFLOW_FRAMED_STREAM_MAX_RECONNECTS`
+
+- Default: `50`
+- Consecutive reconnect cap for framed stream readers.
+
+### `WORKFLOW_FRAMED_STREAM_MAX_TOTAL_RECONNECTS`
+
+- Default: `1000`
+- Total reconnect cap per stream session.
+
+### `WORKFLOW_WAIT_CONTINUATION_MAX_DELAY_SECONDS`
+
+- Default: `82800` (23 hours)
+- Longest single queue delay used for `sleep()` continuations.
+- If a wait is longer than this, Workflow queues one continuation for the maximum delay, then queues another continuation after that message fires, repeating until the wait's target time is reached.
+
+### `WORKFLOW_NEAR_ELAPSED_WAIT_THRESHOLD_SECONDS`
+
+- Default: `2`
+- Clock-skew tolerance for wait continuations that arrive near their target time.
+
+### `WORKFLOW_DEFERRED_CHECK_DELAY_MS`
+
+- Default: `100`
+- Delay before the unconsumed-event check fires.
+- Minimum: `10`.
+
+### `WORKFLOW_LOCK_POLL_INTERVAL_MS`
+
+- Default: `10`
+- Poll interval for detecting stream lock release.