workflow 5.0.0-beta.5 → 5.0.0-beta.50

package/docs/configuration/runtime-tuning.mdx

@@ -0,0 +1,376 @@
+---
+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
+---
+
+The runtime reads these variables 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.
+- Applies whenever the World cannot hold a read open. When it can, the wait below replaces most of this polling and the interval only paces retries.
+
+### `WORKFLOW_RETURN_VALUE_WAIT_MS`
+
+- Default: `50000`
+- Minimum: `1`
+- How long a single wait for a terminal run status may block, when the World supports waiting (`world.runs.waitForTerminalStatus()`). `Run.returnValue` re-issues the wait until the run finishes, so this bounds one request rather than the total wait.
+- `50000` is the largest value the Vercel World can actually request: it clamps the ask to its 60s per-request HTTP timeout minus 10s of headroom, so the budget always expires as a response carrying the run's current status rather than as a client-side timeout. Raising this alone has no effect; raise `WORKFLOW_REQUEST_TIMEOUT_MS` as well.
+- Read by the process awaiting `Run.returnValue`, like the interval above.
+
+### `WORKFLOW_RETURN_VALUE_MAX_LONG_POLLS`
+
+- Default: `10`
+- Minimum: `1`
+- How many consecutive waits `Run.returnValue` issues before falling back to interval polling for the rest of the await.
+- It never ends the await. A run that outlives the cap continues waiting on `WORKFLOW_RETURN_VALUE_POLL_INTERVAL_MS` instead.
+- Runs longer than roughly `WORKFLOW_RETURN_VALUE_MAX_LONG_POLLS` x `WORKFLOW_RETURN_VALUE_WAIT_MS` therefore spend most of their life interval polling, which costs more requests than continuing to wait would. Raise it if you routinely await long runs.
+- Read by the process awaiting `Run.returnValue`, like the interval above.
+
+### `WORKFLOW_RETURN_VALUE_LONG_POLL`
+
+- Default: enabled
+- Set to `0` or `false` to stop `Run.returnValue` from waiting and restore fixed-interval polling on `WORKFLOW_RETURN_VALUE_POLL_INTERVAL_MS` exactly.
+- The kill switch for the wait. Worlds that do not implement waiting are already on the interval path, so this changes nothing for them.
+- Read by the process awaiting `Run.returnValue`, like the interval above.
+
+## 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. Workflow calibrates the default to record failure before the queue expires the message.
+
+### `WORKFLOW_MAX_EVENTS`
+
+- Default: `25000`
+- Positive-integer event limit reported by the Local World and enforced by the runtime as `MAX_EVENTS_EXCEEDED`.
+- The Local and Postgres Worlds also use it as the maximum number of events returned when `events.list()` is called without a limit. If more events exist, the response includes `hasMore: true` and a continuation cursor.
+- The Vercel World receives its event limit from the service; this environment variable does not override that service-owned value.
+- Invalid or non-positive values fall back to the default.
+
+### `WORKFLOW_REPLAY_DIVERGENCE_MAX_RETRIES`
+
+- Default: `3`
+- Recovery replays before replay divergence is recorded as corruption.
+
+### `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_RESILIENT_STEP_DISPATCH`
+
+- Default: disabled
+- When a suspension hands newly created steps to the queue, the runtime publishes each step's execution message in parallel with its `step_created` event write instead of sequencing them, cutting a round trip per dispatched step. The message also carries the serialized step input (`stepInput`), so a transient `step_created` write failure (429 / 5xx / transport) still executes the step. The queue consumer idempotently re-ensures the event before running it, converging with the producer's write on the step's correlation ID. This mirrors resilient start (`runInput`) and the legacy lazy hook resume's `hookInput` (which current producers no longer send; see [durable hook resume](/docs/changelog/lazy-hook-resume)).
+- It is off by default because the publish races the create's verdict, and a create can come back refused: as a duplicate this replay should stop pursuing, or as a [stale write](#stale-reads-and-why-nothing-has-to-be-rejected) on a World that refuses rather than reports. Either way the message carrying the payload is already out, so the consumer can materialize a step whose create was refused, and nothing orders the verdict before the consumer's redelivery re-ensure. The sequential path is the only one that gives the message a happens-after edge over it.
+- Even when enabled, the runtime falls back to the sequential create-then-publish dispatch when the step input is too large to inline on the queue message, or when the run's queue transport cannot carry binary payloads (pre-CBOR spec versions).
+- Producer-side recoveries are reported on the suspension span as `workflow.step.resilient_dispatch_recovered`; a consumer that materialized the event reports `workflow.step.resilient_dispatch_materialized`.
+- Set `1` to enable it.
+
+### Stale reads, and why nothing has to be rejected
+
+- Not a variable: this is how a replay working from an out-of-date event log stays correct, and why no World needs a precondition guard to make it so.
+- Three properties work together. A reader's log is always a **prefix** of the run's log, never a prefix with a hole in it. The World allocates positions at commit, so nothing lands behind a position a reader has already passed. Replay is **deterministic on a prefix**: the same prefix always yields the same decisions, so a shorter log does not mean a different run, only a run that has not caught up. Every write **reports what it missed**: a creation names the position it replayed from (`eventCount`), and the World returns the events occupying the positions it was pushed past. The replay merges those and continues, correcting itself on the write rather than on a read.
+- So a stale replay costs a merge, not a rejection. None of the shipped Worlds refuses a write for being stale.
+- A World *may* refuse instead, with 412 ([`PreconditionFailedError`](/docs/api-reference/workflow-errors/precondition-failed-error)). This is appropriate when it allocates positions somewhere other than the commit and cannot report a gap reliably. 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 after spending the restart budget. It never retries the rejected write as-is because a replay working from a corrected log derives different events.
+- A World that does refuse should only ever do so on evidence, and accept the write in every other case. A rejection then always means the position was stale, while the absence of one proves nothing about currency.
+- Two runtime behaviors follow from the properties above rather than from any fence. 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) stays active while the run has an open hook. A `hook_received` event missed by the delta window is observed one iteration later, and the next write brings it back. While a hook is open, inline steps take the await-then-run path even when optimistic inline start is enabled. Several invocations race for one step's claim there, and awaiting it means the body runs only for the writer that won.
+
+### `WORKFLOW_SLOT_GAP_CHECK`
+
+- Default: enabled
+- A replay checks that the [event log](/docs/how-it-works/event-sourcing#event-ids) it loaded is dense before it runs, and fails the run with [`CORRUPTED_EVENT_LOG`](/docs/errors/corrupted-event-log) when a position below the log's highest holds no event. A log missing only its first position, meaning a run whose `run_created` is still being written, is left alone.
+- A position can be briefly empty while the write that occupies it is still committing, so the check re-reads the log a few times before it decides, and the replay continues from whichever log it settled on.
+- The check trades one failure for another. Most holes stand for an event that never happened, and replaying past those is correct. A hole standing for an event that did happen looks identical, and replaying past that one produces a run whose result is silently wrong. Failing is the recoverable side of that trade.
+- Set `0` to replay across holes instead.
+
+### `WORKFLOW_SEALED_LOG`
+
+- Default: enabled
+- New runs are created at the sealed-log spec version, in which the World's backend assigns each event its position *before* the write commits rather than letting concurrent writers race for one. Concurrent writes then never contend for a position, which is what makes a wide fan-out cheap.
+- The price of assigning positions in advance is that a writer which claims one and then dies leaves a position no writer will ever fill. The backend closes such a position by writing a `noop` event into it once it can prove the position was abandoned, so a reader still sees the dense log it needs. Replay steps over a `noop` without delivering it to the workflow or advancing the deterministic clock. Its timestamp belongs to whichever reader sealed it, not to the run.
+- Set `0` to put a deployment back on the previous scheme, where each position is allocated by the write that occupies it. Use this as the kill switch if position assignment turns out to be at fault for event-log problems.
+- Existing runs are unaffected either way. A run's spec version is stamped once, at creation, and read from the run for the rest of its life, so flipping this changes only what *new* runs get, and a run in flight keeps the scheme it started on. Every build reads sealed logs regardless of the setting.
+- A run created at the sealed-log version can only be replayed by a reader that knows to skip `noop` events. That includes every runtime on this release train, but a runtime that pins its own accepted spec range separately, such as the Python runtime, has to catch up before it can read these runs. Switch this off in an environment where it has not.
+- Only the Vercel World seals. The Local and Postgres Worlds allocate each position at the commit that occupies it, so they cannot leave a hole and never write a `noop`; the setting still moves the version they stamp, so the fleet stays on one spec.
+
+### `WORKFLOW_PRECONDITION_MAX_INPROCESS_RESTARTS`
+
+- Default: `3`
+- How many times a single invocation restarts its replay in-process after an event creation is [rejected as stale](#stale-reads-and-why-nothing-has-to-be-rejected) before it falls back to a re-invocation. No shipped World rejects one, so this budget is reserved for a World that chooses to.
+- 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 after the in-process budget fails to catch up. The delay gives the other writers time to quiesce.
+
+### `WORKFLOW_LOG_ORDER_DRAWS`
+
+- Default: enabled
+- Experimental. Pins correlation-ID draw order to event-log order. A branch-deciding delivery (a step result, hook payload, or wait completion) resolves to the workflow only after every earlier-in-log delivery's continuation has fully quiesced, and never ahead of a lower-slot delivery that is committed to happening.
+- Without it, a delivery that resolves while an earlier delivery's continuation is still a few microtask hops from its next step/hook/wait call can overtake it on the run's shared correlation-ID sequence. Draw order, and therefore correlation IDs, then depends on how much of the event log a replay had loaded. Two concurrent replays holding different-length prefixes can bind one ID to two different entities, failing the run with `CORRUPTED_EVENT_LOG`.
+- Costs one event-loop turn (roughly 15 to 20 microseconds via `setImmediate`) per branch-deciding delivery during replay, and more when continuations genuinely overlap. Measurements on a 100-step sequential replay show about 2 ms added end to end.
+- Only applies to the default Node.js VM engine. `WORKFLOW_VM=quickjs` has its own event feed and correlation-ID sequence and is unaffected by this setting.
+- Correlation IDs of runs created before the setting changed are not affected on platforms where a run keeps replaying on the deployment it started on. Elsewhere, only change it while no runs are in flight.
+- Set `0` to opt back into arrival-order delivery resolution. Only the literal value `0` opts out; `false` or `off` leave it enabled.
+
+## Inline execution
+
+### `WORKFLOW_V2_TIMEOUT_MS`
+
+- Default: derived from the runtime deadline. The value is `600000` when the invocation has 25 minutes or more left, `300000` when it has 10 minutes or more, and `120000` otherwise.
+- 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.
+- The default comes from `World.getRuntimeDeadline()`, so raising a function's `maxDuration` widens the inline budget without configuration. Worlds that do not report a deadline get the flat `120000`. Setting this variable to a finite positive number overrides the tiering entirely.
+
+### `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
+- Node.js VM engine only. 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. QuickJS manages its own retained inline loop independently of this setting.
+- A step- or attribute-driven suspension can keep the VM retained even when hooks or waits are open or created at the same boundary. Hook- or wait-only suspensions park the invocation because nothing in the current delivery can advance them, with one exception: when the hook's own create is what the workflow is waiting on (a `hook.getConflict()` awaiter, or a create whose token is already claimed), the invocation resumes the retained VM over the committed `hook_created` or `hook_conflict` instead of re-invoking through the queue. Any replay divergence falls 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 because serialization never calls them. A boundary falls back to a full replay only when serializing its arguments runs code the workflow controls, such as a getter, a proxy, or a custom class serializer, or computes an `Error`'s stack trace.
+- Set `0` or `false` to replay the Node.js workflow 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 redispatching and reexecuting the step. See [Inline step message ownership](/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 and 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**. Review 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` apply to 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, including `digest`, throw with guidance to move to a step function. The node engine supports `digest`.
+  - `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.
+
+### `WORKFLOW_QUICKJS_BASELINE_SNAPSHOT`
+
+- Default: enabled
+- Only read when `WORKFLOW_VM=quickjs`.
+- Evaluates the workflow bundle once per function instance, snapshots the resulting VM, and restores that snapshot at the start of every invocation instead of re-evaluating the bundle. This is the dominant share of QuickJS VM startup: roughly 77 ms to 3 ms to first suspension for a 1.3 MB bundle.
+- A bundle whose module scope consumes randomness, reads the clock, or replaces a serialization intrinsic cannot be snapshotted safely. The runtime detects these cases when preparing the snapshot and falls back to per-invocation evaluation.
+- Set `0` or `false` to always evaluate the bundle per invocation.
+
+## 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 take the event-log requests off HTTP/2 entirely, back to one request per HTTP/1.1 connection. Use this as the kill switch if HTTP/2 turns out to be at fault for event delivery problems.
+- Has no effect when `WORKFLOW_NODE_HTTP` is enabled, which takes the whole HTTP/2 path away.
+
+### `WORKFLOW_NODE_HTTP`
+
+- Default: disabled
+- Makes the Vercel and Local Worlds issue their HTTP requests through Node's built-in `node:http` and `node:https` modules, instead of the HTTP client library those Worlds normally use.
+- Set `1` to switch to Node's modules. Read the trade-offs below first: they cost throughput on every deployment, which is why this is opt-in.
+- Use it when that library is not an option: a bundler that mangles it, a runtime that does not ship a working copy of it, or a transport-level fault you want to rule out. It is not reached by way of `fetch()` either, so a runtime whose `fetch()` is built on the same library is still covered.
+
+Node's own modules do less than the client they replace, so enabling this drops the per-call-site tuning the Worlds configure:
+
+- Event-log requests lose HTTP/2, so concurrent reads and writes no longer share one connection, and the enlarged HTTP/2 receive windows no longer apply. This is the largest difference, and it slows down replays that read a big event log. It does not apply to event writes on the [WebSocket events transport](/docs/configuration/worlds#workflow_events_transport), which is the default and takes neither transport.
+- Requests lose their transport-level retry. Failures still surface to the layers above, which retry event writes and redeliver queue messages, so nothing is silently dropped, but a failure that a same-connection retry would have hidden now costs a full redelivery.
+- Stream close loses its retry of retriable server errors. A transient failure at close can leave a stream marked closing until the run expires, where it would previously have resolved on the retry.
+
+Connection pooling, keep-alive, and the request, header, and body deadlines are preserved. Node's agents configure pooling and keep-alive, and each request receives the deadlines from the Local World's two queue timeouts or the same defaults that the Vercel World's HTTP client currently applies. Queue sends are the partial exception: that client takes no transport override, so it cannot move to Node's modules. It does honor this variable, by dispatching through the runtime's own copy of the library rather than the copy the World bundles, which is the distinction that matters when the bundled copy is the thing that does not work.
+
+A `dispatcher` passed to `createVercelWorld()` still wins over this variable. The variable chooses which transport the World builds when you have not supplied one.
+
+### `WORKFLOW_VERCEL_QUEUE_TIMEOUT_MS`
+
+- Default: `30000`
+- Total deadline for one request the Vercel World's queue client makes, measured from the moment it is handed to the transport, so it also covers time the request spends waiting for a free connection.
+- Clamped to `[5000, 120000]`.
+- This is the only request path the World cannot bound with `WORKFLOW_REQUEST_TIMEOUT_MS`, because the queue client makes its own calls and accepts no override for them. Without a deadline here, a queue acknowledgement that never completes holds the invocation until the platform kills it, and a killed invocation never acknowledges, so the message is redelivered.
+- Keep it below the queue's visibility-renewal interval (60 seconds) so a failed call has room to surface and be retried before the message lease lapses.
+
+### `WORKFLOW_VERCEL_QUEUE_CONNECTIONS`
+
+- Default: `64`
+- Connections the Vercel World's queue client may open to the queue service.
+- Clamped to `[1, 1024]`.
+- Sized much higher than the World's other connection pools on purpose. The queue client makes roughly two small requests per invocation, so its concurrency tracks how many invocations a compute instance is serving at once rather than any per-request fan-out. Lower it only if you have a reason to cap sockets; too low turns invocation concurrency into the limit on how fast messages can be acknowledged.
+
+## 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. This opt-in setting trades first-chunk latency for larger batches and can benefit 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.
+
+## Limits
+
+### `WORKFLOW_MAX_EVENTS_OVERRIDE`
+
+- Default: unset
+- Lowers the per-run event ceiling supplied by the World. A run whose event log reaches the ceiling fails with `MAX_EVENTS_EXCEEDED`, which stops a runaway loop from growing its log without bound.
+- Clamp-down only: it never raises the World's limit, and it applies even when the World supplies none. With no World limit and no override, nothing is enforced.
+- The Local and Vercel Worlds both supply a limit; the Local World defaults to 25,000 and is configurable with [`WORKFLOW_MAX_EVENTS`](/docs/configuration/worlds#workflow_max_events).