workflow 5.0.0-beta.41 → 5.0.0-beta.42

package/docs/api-reference/workflow-errors/precondition-failed-error.mdx

@@ -8,9 +8,9 @@ related:
   - /docs/api-reference/workflow-errors/entity-conflict-error
 ---
 
-`PreconditionFailedError` is thrown by world implementations when an event creation is rejected because the client's event-log snapshot is stale — either a newer out-of-band event (such as a received hook or a completed step) was recorded after the snapshot the client replayed from, or the snapshot is missing an event recorded at or before it. It corresponds to HTTP 412 Precondition Failed semantics.
+`PreconditionFailedError` is thrown by world implementations when an event creation is rejected because the client's event-log snapshot is stale: the log already held more events than the position the creation named. It corresponds to HTTP 412 Precondition Failed semantics.
 
-This only occurs while the optimistic-concurrency guard is enabled (`WORKFLOW_PRECONDITION_GUARD`, on by default — see [Runtime Tuning](/docs/configuration/runtime-tuning)); event creations that carry no snapshot are never rejected with this error.
+No world in this repository throws it. A stale replay does not need to be refused: its log is a prefix rather than a prefix with a hole in it, replay is deterministic on a prefix, and the write it makes next comes back carrying the events it was pushed past (see [Stale reads](/docs/configuration/runtime-tuning#stale-reads-and-why-nothing-has-to-be-rejected)). The error and the runtime's handling of it remain for a world that would rather refuse than report — one that allocates positions somewhere other than the commit, and so cannot report a gap reliably. Event creations that carry no position are never rejected with it.
 
 A world rejects only on evidence and accepts the creation whenever it cannot decide, so this error always means the snapshot really was stale — but not receiving it does not prove the snapshot was current.
 

package/docs/api-reference/workflow-runtime/world/analytics.mdx

@@ -22,6 +22,10 @@ keywords:
 
 `world.analytics` is an optional, read-only namespace for observability surfaces — dashboards, CLIs, and admin tools that list large numbers of runs without touching payload data.
 
+For observability and inspection listings, prefer this namespace over
+[`world.runs.list()`](/docs/api-reference/workflow-runtime/world/storage#runslist).
+The storage API remains available for operational and payload-bearing reads.
+
 It differs from [Storage](/docs/api-reference/workflow-runtime/world/storage) in two ways:
 
 - **Metadata only.** Results never include run input/output, step data, or hook tokens. There is no `resolveData` option.

package/docs/api-reference/workflow-runtime/world/storage.mdx

@@ -133,7 +133,10 @@ const result = await world.events.listByCorrelationId({ // [!code highlight]
 
 ## world.runs
 
-Materialized from run events. Use it to list and inspect workflow runs.
+Materialized from run events. Use it for canonical operational reads, including
+reads that require workflow input or output data. For observability dashboards,
+inspection tools, and historical listings, use
+[`world.analytics.runs.list()`](/docs/api-reference/workflow-runtime/world/analytics#runslist).
 
 ### runs.get()
 
@@ -163,6 +166,14 @@ const result = await world.runs.list({ // [!code highlight]
 
 **Returns:** `{ data: WorkflowRun[], cursor?: string }`
 
+<Callout type="warn">
+  Observability and inspection usage of `world.runs.list()` is deprecated. Use
+  [`world.analytics.runs.list()`](/docs/api-reference/workflow-runtime/world/analytics#runslist)
+  for metadata-only, plan-aware queries backed by the observability pipeline.
+  `world.runs.list()` remains supported for operational and payload-bearing
+  reads.
+</Callout>
+
 ### Cancelling Runs
 
 To cancel a run, create a `run_cancelled` event via `world.events.create()` (see [world.events](#worldevents) above), or use the CLI or Web UI helpers.

package/docs/configuration/runtime-tuning.mdx

@@ -71,17 +71,23 @@ For example, a workflow can run a 10-minute inline step even with `WORKFLOW_REPL
 - 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`
+### `WORKFLOW_RESILIENT_STEP_DISPATCH`
 
-- 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.
+- 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 lazy hook resume (`hookInput`).
+- 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 do it together. A reader's log is always a **prefix** of the run's log, never a prefix with a hole in it — positions are allocated by the World 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. And 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)) — appropriate when it allocates positions somewhere other than the commit and cannot report a gap reliably. The runtime handles that: it 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, 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 really 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` missed by the delta window is observed one iteration later, and the next write brings it back. And 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`
 
@@ -94,7 +100,7 @@ For example, a workflow can run a 10-minute inline step even with `WORKFLOW_REPL
 ### `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.
+- 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`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "workflow",
-  "version": "5.0.0-beta.41",
+  "version": "5.0.0-beta.42",
   "description": "Workflow SDK - Build durable, resilient, and observable workflows",
   "main": "dist/typescript-plugin.cjs",
   "type": "module",
@@ -59,18 +59,18 @@
   },
   "dependencies": {
     "ms": "2.1.3",
-    "@workflow/astro": "5.0.0-beta.41",
-    "@workflow/cli": "5.0.0-beta.41",
-    "@workflow/core": "5.0.0-beta.41",
-    "@workflow/errors": "5.0.0-beta.16",
+    "@workflow/astro": "5.0.0-beta.42",
+    "@workflow/cli": "5.0.0-beta.42",
+    "@workflow/core": "5.0.0-beta.42",
+    "@workflow/errors": "5.0.0-beta.17",
     "@workflow/typescript-plugin": "5.0.0-beta.5",
     "@workflow/utils": "5.0.0-beta.8",
-    "@workflow/next": "5.0.0-beta.41",
-    "@workflow/nest": "5.0.0-beta.41",
-    "@workflow/nitro": "5.0.0-beta.41",
-    "@workflow/nuxt": "5.0.0-beta.41",
-    "@workflow/sveltekit": "5.0.0-beta.41",
-    "@workflow/rollup": "5.0.0-beta.41"
+    "@workflow/next": "5.0.0-beta.42",
+    "@workflow/nest": "5.0.0-beta.42",
+    "@workflow/nitro": "5.0.0-beta.42",
+    "@workflow/nuxt": "5.0.0-beta.42",
+    "@workflow/sveltekit": "5.0.0-beta.42",
+    "@workflow/rollup": "5.0.0-beta.42"
   },
   "devDependencies": {
     "@types/ms": "2.1.0",