workflow 5.0.1 → 5.1.0

package/docs/how-it-works/code-transform.mdx

@@ -74,8 +74,9 @@ flowchart LR
 
 ## Detailed transformation examples
 
-<Tabs items={["Step Mode", "Workflow Mode", "Detect Mode"]}>
-<Tab value="Step Mode">
+<TabsWithChildren tabs={["Step Mode","Workflow Mode","Detect Mode"]}>
+
+<TabContent order={1}>
 
 **Step Mode** creates the registration bundle that the combined flow handler imports (it is not an HTTP route), and is also the transform framework loaders apply to your application code.
 
@@ -126,8 +127,9 @@ handleUserSignup.workflowId = "workflow//workflows/user.js//handleUserSignup"; /
 
 **ID format:** Step IDs follow the pattern `step//{filepath}//{functionName}`, where the file path is relative to your project root.
 
-</Tab>
-<Tab value="Workflow Mode">
+</TabContent>
+
+<TabContent order={2}>
 
 **Workflow Mode** creates the workflow execution bundle served at `/.well-known/workflow/v1/flow`.
 
@@ -176,8 +178,9 @@ handleUserSignup.workflowId = "workflow//workflows/user.js//handleUserSignup"; /
 
 **ID format:** Workflow IDs follow the pattern `workflow//{filepath}//{functionName}`. The `workflowId` property is attached to the function so [`start()`](/docs/api-reference/workflow-api/start) works at runtime.
 
-</Tab>
-<Tab value="Detect Mode">
+</TabContent>
+
+<TabContent order={3}>
 
 **Detect Mode** is a lightweight, non-transforming mode used during the build's discovery phase.
 
@@ -216,8 +219,9 @@ export async function handleUserSignup(email: string) {
   **Working without the app-code loader:** Frameworks apply the step-mode transform to application code by default, which is what gives `start(handleUserSignup)` its automatic IDs and type safety. If your setup can't run the loader, you can instead construct workflow IDs manually using the pattern `workflow//{filepath}//{functionName}`, look them up in the build manifest, and pass them to `start()` as strings.
 </Callout>
 
-</Tab>
-</Tabs>
+</TabContent>
+
+</TabsWithChildren>
 
 ## Generated files
 

package/docs/how-it-works/encryption.mdx

@@ -36,7 +36,9 @@ Metadata such as workflow names, step names, entity IDs, timestamps, and lifecyc
 
 ### Compression
 
-Payloads are compressed before encryption. A format prefix on the stored value records the compression codec (gzip, with zstd support in the format), and the inner payload keeps its own serialization format prefix after decompression. Repetitive payloads compress heavily. AI token streams average around 80% smaller, reducing storage and network transfer. Like encryption, compression is automatic and requires no code changes.
+Payloads are compressed before encryption. A format prefix on the stored value records the compression codec, and the inner payload keeps its own serialization format prefix after decompression. Repetitive payloads compress heavily. AI token streams average around 80% smaller, reducing storage and network transfer. Like encryption, compression is automatic and requires no code changes.
+
+The codec is zstd when both the writer and the run's deployment run Node.js 22.15+ (or 23.8+), and gzip otherwise. Runs started on an older Node.js version stay readable after you upgrade the project's Node.js version. To force a codec, set [`WORKFLOW_COMPRESSION_CODEC`](/docs/configuration/runtime-tuning#workflow_compression_codec).
 
 ### Key management
 

package/docs/whats-new.mdx

@@ -154,7 +154,7 @@ All three first-party Worlds now implement it: Vercel accepts up to 30 days, and
 - **A run cannot be forked across environments.** `start()` stamps the environment it was called from onto the queue message, and a deployment refuses a delivery whose run was created in a different environment. Previously a preview client and a production deployment could each hold half of one run ID.
 - **An experimental QuickJS VM engine.** Set [`WORKFLOW_VM=quickjs`](/docs/configuration/runtime-tuning#workflow_vm) to run workflow functions in a QuickJS VM compiled to WebAssembly instead of `node:vm`, for platforms that do not provide `node:vm`. Replay semantics are identical, but the available globals are not: check the differences before switching an existing deployment.
 - **Experimental dynamic workflows.** Pass workflow source as a string to `start()` to run orchestration assembled after deployment over steps already deployed with your app. The code is stored with the run (encrypted on Vercel), so replays always execute the code the run started with. Off unless the deployment sets `WORKFLOW_EXPERIMENTAL_DYNAMIC_WORKFLOWS=1`. See [Dynamic Workflows](/docs/advanced/dynamic-workflows).
-- **An opt-in WebSocket transport for event writes** on the Vercel World, which ships a run's events over one socket instead of one HTTP request each. Set [`WORKFLOW_EVENTS_TRANSPORT=ws`](/worlds/vercel#workflow_events_transport) to opt in. Any other value, including unset, keeps HTTP. Tracing is unaffected: each write still emits an `http POST` client span, synthesized around the frame, with the transport on `workflow.events.transport`.
+- **A WebSocket transport for event writes** on the Vercel World, which ships a run's events over one socket instead of one HTTP request each. It is the default; set [`WORKFLOW_EVENTS_TRANSPORT=http`](/worlds/vercel#workflow_events_transport) to opt out. Tracing is unaffected: each write still emits an `http POST` client span, synthesized around the frame, with the transport on `workflow.events.transport`.
 - **`await run.returnValue` waits instead of polling.** Reading a run's result long-polls the World until the run reaches a terminal status, rather than asking again on a fixed interval. A result is observed as soon as it exists, and an idle wait costs one open request instead of a request per tick. Worlds that do not implement the long poll keep the interval.
 - **An event arriving mid-replay no longer fails the run.** A hook resume or step completion landing while a replay is in flight used to be able to fail it with [`CORRUPTED_EVENT_LOG`](/docs/errors/corrupted-event-log). Writes now come back with the events the replay had not seen, and the event is held for whichever part of the workflow awaits it. A run only fails when the log is genuinely missing a position.
 

package/docs/worlds/building-a-world.mdx

@@ -158,6 +158,8 @@ interface Storage {
 
 **Batch writes:** `events.createBatch()` is optional, and implementing it is what declares it. The runtime folds a suspension's `step_created` and `wait_created` writes into batches only when the method exists, and otherwise takes the single-event path unchanged. Implement it with real atomicity per attempt, so a lost race leaves nothing behind, or do not implement it at all. The events land in request order at consecutive positions, and a concurrent writer may push the whole batch above the caller's view of the log. No skipped-event report accompanies the result, so a position-tracking caller compares the committed positions against what it expected and reloads. Reject the whole batch, with a request-level error, for `run_created`, `run_started`, `run_cancelled`, `hook_created`, `hook_disposed`, `attr_set`, for more events targeting one entity than a single write can express, and for a batch over your own size caps. The one legal same-entity pair is `step_created` followed by `step_started`, which creates the step born-running, and there the input must ride the `step_created`.
 
+**Throttled step results:** `step_completed`, `step_retrying`, and a `step_failed` marked with `afterStepBody: true` in `CreateEventParams` record a step body that already ran. If your World retries throttled writes, keep these waiting longer than other writes, because losing one to queue redelivery runs the body again. `@workflow/world-vercel` waits until the invocation's deadline. The flag is advisory, and a World may ignore it.
+
 **Run creation:** For `run_created` events, the `runId` parameter may be a client-provided string or `null`. When `null`, your World generates and returns a new `runId`.
 
 **Event data resolution:** `events.list()` and `events.create()` accept `resolveData: 'skip-step-inputs'`, and the runtime replays with it. The World may leave `input` out of `step_created` and `step_started` events, and returns everything else as for `'all'`. Treat any value other than `'none'` as `'all'`, because a World that tests `resolveData === 'all'` strips step results and breaks every replay. Map the value with `entityResolveData()` from `@workflow/world` before passing it to an entity read.
@@ -449,7 +451,10 @@ that lifetime, so the session's `write(chunkSeq, chunks)` receives a sequence
 number that is writer-local rather than stream-global. That is what lets a
 World order concurrent writers to the same stream. The session's `close()` must
 not resolve before every prior write is durable; `dispose()` is optional and
-releases transport resources without ending the stream. A World that does not
+releases transport resources without ending the stream. Optional `release()`
+retires an idle transport after the runtime drains a released writer. Unlike
+`dispose()`, it must leave later `write()` and `close()` usable, for example
+by switching that writer to stateless HTTP. A World that does not
 implement `createWriteSession` is unaffected: the runtime uses
 `write`/`writeMulti`/`close` exactly as before.
 

package/docs/worlds/postgres.mdx

@@ -48,42 +48,22 @@ WORKFLOW_POSTGRES_URL="postgres://user:password@host:5432/database"
 
 Run the migration script to create the necessary tables in your database. Ensure `WORKFLOW_POSTGRES_URL` or `DATABASE_URL` is set when running this command:
 
-<Tabs items={["npm", "pnpm", "Yarn", "Bun"]}>
-
-<Tab value="npm">
-
-```bash
+```bash tab="npm"
 npx --package=@workflow/world-postgres bootstrap
 ```
 
-</Tab>
-
-<Tab value="pnpm">
-
-```bash
+```bash tab="pnpm"
 pnpm dlx --package @workflow/world-postgres bootstrap
 ```
 
-</Tab>
-
-<Tab value="Yarn">
-
-```bash
+```bash tab="Yarn"
 yarn dlx --package @workflow/world-postgres bootstrap
 ```
 
-</Tab>
-
-<Tab value="Bun">
-
-```bash
+```bash tab="Bun"
 bunx --package @workflow/world-postgres bootstrap
 ```
 
-</Tab>
-
-</Tabs>
-
 <Callout type="info">
 The migration is idempotent and can safely be run as a post-deployment lifecycle script.
 </Callout>
@@ -154,9 +134,9 @@ still adds overhead. Pulling in `workflow/runtime` from a server-startup hook pu
 the whole runtime into the cold-start path before the first request is served.
 </Callout>
 
-<Tabs items={["Next.js", "SvelteKit", "Nitro"]}>
+<TabsWithChildren tabs={["Next.js","SvelteKit","Nitro"]}>
 
-<Tab value="Next.js">
+<TabContent order={1}>
 
 Create an `instrumentation.ts` file in your project root:
 
@@ -174,9 +154,9 @@ export async function register() {
 Learn more about [Next.js Instrumentation](https://nextjs.org/docs/app/guides/instrumentation).
 </Callout>
 
-</Tab>
+</TabContent>
 
-<Tab value="SvelteKit">
+<TabContent order={2}>
 
 Create a `src/hooks.server.ts` file:
 
@@ -194,9 +174,9 @@ export const init: ServerInit = async () => {
 Learn more about [SvelteKit Hooks](https://svelte.dev/docs/kit/hooks).
 </Callout>
 
-</Tab>
+</TabContent>
 
-<Tab value="Nitro">
+<TabContent order={3}>
 
 Create a plugin to start the world on server initialization:
 
@@ -225,9 +205,9 @@ export default defineNitroConfig({
 Learn more about [Nitro Plugins](https://v3.nitro.build/docs/plugins).
 </Callout>
 
-</Tab>
+</TabContent>
 
-</Tabs>
+</TabsWithChildren>
 
 <Callout type="info">
 The Postgres World requires a long-lived worker process that polls the database for jobs. This does not work on serverless environments. For Vercel deployments, use the [Vercel World](/worlds/vercel) instead.

package/docs/worlds/upgrading-to-v5.mdx

@@ -99,7 +99,7 @@ This bites rather than merely wasting memory because the runtime caches the *Wor
 
 **One World per process.** The workflow entrypoint's queue handler is now built from the runtime World that `getWorld()` returns, rather than from `getWorldHandlers()`. A stateful World is no longer instantiated twice in one process, so it stops getting duplicate connection pools and duplicate queue workers. If you added your own de-duplication to work around that, it is now redundant, though harmless if it keys on process-wide state.
 
-**Your own transport is your own business, except for the tracing.** How a World ships events to its backend is unconstrained: `@workflow/world-vercel` can opt into a WebSocket and falls back to HTTP. What is constrained is what a reader of a trace sees. A non-HTTP transport still has to emit the per-event client span that an HTTP write would, or the per-event view of a run silently disappears. See [`WORKFLOW_EVENTS_TRANSPORT`](/worlds/vercel#workflow_events_transport) for the span shape and attributes the Vercel World uses, including a separate span for the handshake.
+**Your own transport is your own business, except for the tracing.** How a World ships events to its backend is unconstrained: `@workflow/world-vercel` uses a WebSocket by default and falls back to HTTP. What is constrained is what a reader of a trace sees. A non-HTTP transport still has to emit the per-event client span that an HTTP write would, or the per-event view of a run silently disappears. See [`WORKFLOW_EVENTS_TRANSPORT`](/worlds/vercel#workflow_events_transport) for the span shape and attributes the Vercel World uses, including a separate span for the handshake.
 
 **Replay reads the event log with `resolveData: 'skip-step-inputs'`.** A World may leave `input` out of `step_created` and `step_started` events for this value, and must otherwise treat it as `'all'`. A World that tests `resolveData === 'all'`, or validates against `['none', 'all']`, strips step results or rejects the read, and every replay fails. Test for `'none'` instead, or map with `entityResolveData()` from `@workflow/world`. `@workflow/world-testing` covers this case.
 

package/docs/worlds/vercel.mdx

@@ -248,17 +248,19 @@ This setting does not own tenant rollout policy and does not infer server suppor
 
 Writes and close requests execute serially. The first operation waits up to 250 ms for an opted-in socket to open; this is an implementation-level measurement knob, not protocol semantics. If the budget expires, or the upgrade fails or is declined before acceptance, the writer uses HTTP without racing the same operation over both transports. After the socket accepts a write, a missing acknowledgement has an unknown outcome: the writer fails rather than replaying the write over HTTP and risking a duplicate append. A throttled (429) write or close did not apply, so the writer retries it after the server's `Retry-After`, as the HTTP writer does, on the socket if it stays open (or its replacement, after a drain) and otherwise over HTTP. Past 30 seconds of cumulative wait, the write moves to HTTP, whose own 429 retry applies. A close that fails with a 5xx is retried over HTTP, since close is idempotent.
 
+Once a released writer's writes drain, its socket closes without closing the shared stream, and later writes through that same handle go over HTTP. Writers acquired with `getWritable()` inside a step release their socket when the step completes. External `getRun(runId).getWritable()` handles release it on the first `releaseLock()` after pending writes drain, so hold the writer lock for the whole burst to keep writing over the socket.
+
 Before routine authentication expiry or server max duration, the server sends a v1 `drain` control. The client stops sending, lets an already-admitted request receive its reply, and reconnects after the server closes with code 1001. Authentication drains re-resolve a fresh bearer. A request that was sent but receives no reply before close still has an unknown outcome and is never replayed.
 
 Each stream WebSocket message is at most [`WORKFLOW_WS_MAX_MESSAGE_BYTES`](#workflow_ws_max_message_bytes) bytes. A write group larger than the limit is sent as several ordered write requests. A single chunk too large for one message is written over HTTP instead, as are the rest of its writer's writes.
 
 ### `WORKFLOW_EVENTS_TRANSPORT`
 
-Opt-in WebSocket transport for workflow run events, which ships them to the Vercel World over one socket per run instead of one HTTP request each. Default: `http`.
+Workflow run events ship to the Vercel World over a WebSocket instead of one HTTP request each. Default: `ws`.
 
-Set `WORKFLOW_EVENTS_TRANSPORT=ws` to opt in. Only that value (case-insensitive) enables the WebSocket — any other value, including unset, empty, or `http`, keeps HTTP — so a typo fails toward the default rather than enabling a transport nobody asked for.
+Set `WORKFLOW_EVENTS_TRANSPORT=http` to opt out. Only that exact value disables the WebSocket — any other value, including unset or empty, takes it — so a typo fails toward the default rather than silently pinning a deployment to HTTP.
 
-The setting is ignored when the World is configured with `projectConfig` and therefore routes through the `api-workflow` proxy: that endpoint is an HTTP-only REST gateway and does not forward a WebSocket upgrade, so events stay on HTTP. The fallback is silent, because the variable is typically set deployment-wide and a `projectConfig` World (such as the CLI) cannot act on it, and is reported once per process under `DEBUG=workflow:*`. `workflow.events.transport` on the per-write span records which transport actually carried a run.
+The setting is ignored when the World is configured with `projectConfig` and therefore routes through the `api-workflow` proxy: that endpoint is an HTTP-only REST gateway and does not forward a WebSocket upgrade, so events stay on HTTP. The fallback is silent — now that the WebSocket is the default, nothing asked for it — and is reported once per process under `DEBUG=workflow:*`. `workflow.events.transport` on the per-write span records which transport actually carried a run.
 
 Event writes use the WebSocket only while that run's events channel is open. The queue handler opens it for every delivery, so workflows need nothing extra. Code that writes a run's events outside a delivery, such as a custom driver or a long-lived process, opens the channel with `openEventsChannel(runId)`, or those writes go over HTTP. Call the returned release when you're done, because an open socket keeps the process alive:
 
@@ -294,7 +296,7 @@ The WebSocket handshake is itself a span, `workflow.events.ws.connect`, so the c
 
 ### `WORKFLOW_EVENTS_TRANSPORT_WS_OVERRIDE_WORKFLOWS`
 
-Comma-separated workflows whose runs use the WebSocket events transport even when [`WORKFLOW_EVENTS_TRANSPORT`](#workflow_events_transport) is `http` or unset. Use it to move selected workflows onto the WebSocket while the rest of the deployment stays on HTTP. Default: none.
+Comma-separated workflows whose runs use the WebSocket events transport even when [`WORKFLOW_EVENTS_TRANSPORT`](#workflow_events_transport) is `http`. Use it to move selected workflows onto the WebSocket while the rest of the deployment stays on HTTP. Default: none.
 
 Each entry is a workflow's function name, such as `processOrder`, or its full workflow name, such as `workflow//./src/workflows/order//processOrder`. Matching is exact and case-sensitive. A function name matches every workflow with that name, in any file.
 
@@ -302,7 +304,7 @@ Each entry is a workflow's function name, such as `processOrder`, or its full wo
 WORKFLOW_EVENTS_TRANSPORT_WS_OVERRIDE_WORKFLOWS=processOrder,syncInventory
 ```
 
-The override applies to the events channel the queue handler opens for each delivery of a listed workflow's run. The workflow name comes from the delivery's queue, so it covers the run's workflow and step invocations alike. `openEventsChannel(runId, config, { workflowName })` applies it to channels you open yourself; without `workflowName`, only `WORKFLOW_EVENTS_TRANSPORT=ws` opens one. When `WORKFLOW_EVENTS_TRANSPORT=ws` is set, every workflow already uses the WebSocket and the override has no effect.
+The override applies to the events channel the queue handler opens for each delivery of a listed workflow's run. The workflow name comes from the delivery's queue, so it covers the run's workflow and step invocations alike. `openEventsChannel(runId, config, { workflowName })` applies it to channels you open yourself; without `workflowName`, a deployment with `WORKFLOW_EVENTS_TRANSPORT=http` opens none. Unless `WORKFLOW_EVENTS_TRANSPORT=http` is set, every workflow already uses the WebSocket and the override has no effect.
 
 Like other environment variables, the setting is fixed for each deployment, and a run stays on the deployment it started on. Changing it takes effect for runs started on the next deployment; runs already in progress keep the transport of the deployment they're pinned to.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "workflow",
-  "version": "5.0.1",
+  "version": "5.1.0",
   "description": "Workflow SDK - Build durable, resilient, and observable workflows",
   "main": "dist/typescript-plugin.cjs",
   "type": "module",
@@ -58,19 +58,19 @@
     }
   },
   "dependencies": {
-    "@workflow/astro": "5.0.1",
-    "@workflow/cli": "5.0.1",
-    "@workflow/core": "5.0.1",
-    "@workflow/errors": "5.0.1",
+    "@workflow/astro": "5.0.2",
+    "@workflow/cli": "5.0.2",
+    "@workflow/core": "5.1.0",
+    "@workflow/errors": "5.0.2",
     "@workflow/typescript-plugin": "5.0.0",
-    "@workflow/utils": "5.0.0",
+    "@workflow/utils": "5.0.1",
     "ms": "2.1.3",
-    "@workflow/next": "5.0.1",
-    "@workflow/nest": "5.0.1",
-    "@workflow/nitro": "5.0.1",
-    "@workflow/nuxt": "5.0.1",
-    "@workflow/sveltekit": "5.0.1",
-    "@workflow/rollup": "5.0.1"
+    "@workflow/next": "5.0.2",
+    "@workflow/nest": "5.1.0",
+    "@workflow/nitro": "5.0.2",
+    "@workflow/nuxt": "5.0.2",
+    "@workflow/sveltekit": "5.0.2",
+    "@workflow/rollup": "5.0.2"
   },
   "devDependencies": {
     "@types/ms": "2.1.0",