workflow 5.0.0-beta.50 → 5.0.0-beta.52

package/docs/getting-started/python.mdx

@@ -11,7 +11,7 @@ related:
 ---
 
 <CopyPrompt
-  text="Set up Workflow in this Python project. In `pyproject.toml`, add `requires-python = &quot;&gt;=3.12&quot;` and `dependencies = [&quot;vercel-workflow&quot;]` under `[project]`, then add `[[tool.vercel.workflows]]` with `entrypoint = &quot;app.workflows:wf&quot;`. Create `app/workflow.py` with `from vercel import workflow` and `wf = workflow.Workflows()`. Create `app/steps/generate_draft.py`, import `wf`, and define async step functions such as `generate_draft` and `summarize_draft`, decorating each with `@wf.step`. Then create `app/workflows/ai_content_workflow.py`, import `wf` and those step functions, and define `@wf.workflow async def ai_content_workflow(*, topic: str)` to orchestrate them and return the result. In `app/workflows/__init__.py`, export `wf` and import the workflow module so its definitions are registered. From server-side code, start it with `await workflow.start(ai_content_workflow, topic=...)`; use the returned `Run` to access its ID, check its status, or await its return value. Where the workflow needs a durable delay, use `await workflow.sleep(timedelta(days=7))` after importing `timedelta` from `datetime`. Where it needs an external approval event, define a Pydantic model that also extends `workflow.BaseHook`, wait with `.wait(token=...)`, and resume it from server-side code with `.resume(token)`."
+  text="Set up Workflow in this Python project. In `pyproject.toml`, add `requires-python = &quot;&gt;=3.12&quot;` and `dependencies = [&quot;vercel-workflow&quot;]` under `[project]`, then add `[[tool.vercel.workflows]]` with `entrypoint = &quot;app.workflows:wf&quot;`. Create `app/workflow.py` with `from vercel import workflow` and `wf = workflow.Workflows(sandbox_policy=workflow.SandboxPolicy(share_sandboxes=True))`. Create `app/steps/generate_draft.py`, import `wf`, and define async step functions such as `generate_draft` and `summarize_draft`, decorating each with `@wf.step`. Then create `app/workflows/ai_content_workflow.py`, import `wf` and those step functions, and define `@wf.workflow async def ai_content_workflow(*, topic: str)` to orchestrate them and return the result. In `app/workflows/__init__.py`, export `wf` and import the workflow module so its definitions are registered. From server-side code, start it with `await workflow.start(ai_content_workflow, topic=...)`; use the returned `Run` to access its ID, check its status, or await its return value. Where the workflow needs a durable delay, use `await workflow.sleep(timedelta(days=7))` after importing `timedelta` from `datetime`. Where it needs an external approval event, define a Pydantic model that also extends `workflow.BaseHook`, wait with `.wait(token=...)`, and resume it from server-side code with `.resume(token)`."
 />
 
 <Callout type="warn">
@@ -42,9 +42,13 @@ A workflow is a stateful function that coordinates multi-step logic over time. C
 ```python filename="app/workflow.py"
 from vercel import workflow
 
-wf = workflow.Workflows()  # [!code highlight]
+wf = workflow.Workflows(
+    sandbox_policy=workflow.SandboxPolicy(share_sandboxes=True),  # [!code highlight]
+)
 ```
 
+`share_sandboxes=True` reuses a sandbox across workflow runs for faster startup. Module globals are shared between those runs, so workflow code should not mutate global state.
+
 ```python filename="app/workflows/ai_content_workflow.py"
 from app.workflow import wf
 from app.steps.generate_draft import generate_draft, summarize_draft
@@ -96,6 +100,33 @@ async def summarize_draft(*, draft: str):
 
 Each step executes separately from the workflow orchestrator. While the step executes, the workflow suspends without consuming resources. When the step completes, the workflow resumes automatically where it left off.
 
+### Cancellable steps
+
+Pass `cancellable=True` when a workflow may need to stop a running step. This makes normal Python `asyncio` cancellation apply to the step: if a task awaiting the step is cancelled in the workflow, then the task running the step will be cancelled as well. For example, `asyncio.timeout()` cancels the step if it does not finish within the allotted time:
+
+```python filename="app/workflows/report.py"
+import asyncio
+from datetime import timedelta
+
+from app.workflow import wf
+
+
+@wf.step(cancellable=True)  # [!code highlight]
+async def generate_report(*, account_id: str) -> dict[str, str]:
+    return await reporting_service.generate(account_id=account_id)
+
+
+@wf.workflow
+async def report_workflow(*, account_id: str) -> dict[str, str]:
+    try:
+        async with asyncio.timeout(timedelta(minutes=10).total_seconds()):  # [!code highlight]
+            return await generate_report(account_id=account_id)
+    except TimeoutError:
+        return {"status": "timed_out"}
+```
+
+Cancellation is a request, so the workflow waits for the step to terminate before continuing. If the step suppresses its cancellation, it can still return normally.
+
 ## Starting a workflow
 
 Call `workflow.start()` from server-side code to start a workflow. It returns a `Run` that you can use to identify the run, check its status, and wait for its result:
@@ -167,6 +198,18 @@ The string form accepts one or more `<value><unit>` pairs. Supported units:
 
 The sleep consumes no resources. The workflow resumes automatically when the time expires.
 
+`asyncio.sleep()` may also be used to sleep.
+
+## Deterministic workflow helpers
+
+Workflow bodies must be fully deterministic, and so are not allowed to perform operations like reading the system clock or generating randomness using the default generator. Deterministic replacements are provided for use in workflow bodies:
+
+- `workflow.now()` is a deterministic substitute for `datetime.datetime.now`. It returns the time that the last workflow event occurred at.
+- `workflow.time_ns()` is a deterministic substitute for `time.time_ns`.
+- `workflow.random()` returns a `random.Random` instance with a seed based on the run id.
+
+These helpers can only be called from a workflow body. Steps should use the normal system functions.
+
 ## Hooks
 
 A hook lets a workflow wait for external events such as user actions, webhooks, or third-party API responses.
@@ -187,7 +230,7 @@ class Approval(pydantic.BaseModel, workflow.BaseHook):  # [!code highlight]
     notes: str | None = None
 
 @wf.workflow
-async def ai_approval_workflow(*, topic: str):
+async def ai_approval_workflow(*, topic: str) -> None:
     draft = await generate_draft(topic=topic)
 
     # Wait for human approval events
@@ -209,7 +252,8 @@ from app.workflows.approval import Approval
 async def resume(approval: Approval):  # [!code highlight]
     """Resume the workflow when an approval is received"""
 
-    await approval.resume("draft-123")  # [!code highlight]
+    hook = await approval.resume("draft-123")  # [!code highlight]
+    print(f"Resumed workflow run: {hook.run_id}")  # [!code highlight]
     return {"ok": True}
 ```
 
@@ -217,41 +261,51 @@ When a hook receives data, the workflow resumes automatically. You don&apos;t ne
 
 ## Streaming
 
-Steps can stream progress while a workflow is running. Get the run&apos;s writable stream inside a step, write values to it, and close it when no more values will be sent:
+Steps can stream progress while a workflow is running. Streams are associated with workflow runs, can be acquired from inside a workflow or inside a step, and can be passed to workflows and steps as arguments. If a type is specified when getting the stream (or on the type annotation of a step or workflow it is passed to), then Pydantic will be used to encode and decode the type.
 
 ```python filename="app/workflows/streaming.py"
+import pydantic
+
 from app.workflow import wf
 from vercel import workflow
 
-@wf.step
-async def write_progress():
-    writable = workflow.get_writable()  # [!code highlight]
 
+class Progress(pydantic.BaseModel):
+    message: str
+
+
+@wf.step
+async def write_progress(
+    writable: workflow.WorkflowWritable[Progress],  # [!code highlight]
+):
     for message in ["Drafting", "Reviewing", "Complete"]:
-        await writable.write(message)  # [!code highlight]
+        await writable.write(Progress(message=message))  # [!code highlight]
 
     await writable.close()
 
 @wf.workflow
 async def streaming_workflow():
-    await write_progress()
+    writable = workflow.get_writable(type=Progress)
+    await write_progress(writable)  # [!code highlight]
 ```
 
-Read the values from the returned `Run` as they arrive:
+Read and validate the typed values from the returned `Run` as they arrive:
 
 ```python filename="app/api/stream.py"
-from app.workflows.streaming import streaming_workflow
+from app.workflows.streaming import Progress, streaming_workflow
 from vercel import workflow
 
 @app.post("/api/stream")
 async def stream_progress():
     run = await workflow.start(streaming_workflow)
 
-    async for message in run.readable():  # [!code highlight]
-        print(message)
+    async for progress in run.readable(type=Progress):  # [!code highlight]
+        print(progress.message)
 ```
 
-Streams are not closed automatically. Close the writable in the last step that writes to it so readers know when the stream is complete.
+Streams are not closed automatically. It can be manually closed when it is finished so that readers know to terminate.
+
+`readable` and `get_writable` also take a `namespace` parameter, allowing each run to have many distinct streams.
 
 ## Next steps
 

package/docs/how-it-works/event-sourcing.mdx

@@ -267,6 +267,33 @@ Both kinds of skip are logged at `debug`, so neither reaches the console unless
 
 The observability UI grays out events it can identify this way and shows the reason on hover. Its set is narrower than the runtime's because it reads the log without consumer state. A consumer for an entity that is still open can legitimately claim a repeat because each step retry writes another `step_started`. The UI marks a repeat only when no consumer can remain for it: after a terminal event for the same entity or at a second `run_started`, of which the log records one per run. The UI marks nothing on a partial log view, such as one page of a paginated list or search results, because identifying the first copy requires the entire log.
 
+## Events returned on a write
+
+Concurrent invocations of one run write to a shared log, and a write is decided against the log the writer had loaded. When the write lands above other events the writer had not seen, the World can hand those events back on the write's own success response, so the writer merges them and continues rather than discovering the gap on its next read. Two parameters of `events.create()` ask for this:
+
+- **`eventCount`** says how many events the writer held. When the write commits at a higher position than `eventCount + 1`, the World returns the events on the positions in between (the *skipped-slot report*).
+- **`sinceCursor`** is the `events.list()` cursor the writer had read to. The World returns everything after it, the write itself included (the *inline delta*), in the same `events` / `cursor` / `hasMore` shape as a list page.
+
+Both save a reload, so the rule for which writes send them is not about the event type. It is about whether the process that writes **holds a loaded log it will keep deciding from**: its own next writes, or the replay it resumes after the write. A writer with no log has nothing to merge a page into, and whoever decides next is a fresh replay that loads the log anyway. Three things must hold for a page to come back: the writer named a position, the World reads a page for that event type (a backend may decline for types whose writer never holds a log), and there is something to return (the report only when positions were skipped; the delta always).
+
+| Event | Writer | Sends | Why |
+|-------|--------|-------|-----|
+| `run_created` | `start()` | Nothing | No log exists yet. |
+| `run_started` | Replay, first write of a delivery | `eventCount` when a log is loaded; no cursor | The `run_started` response already carries the full log as a preload. |
+| `step_created`, `wait_created`, `hook_disposed`, `attr_set` | Suspension handler | `eventCount` | The handler keeps writing from this log and the replay resumes from it. |
+| `hook_created` | Suspension handler | `eventCount` and `sinceCursor` (only when the suspension creates exactly one hook) | The delta is how a hook whose payload already arrived resolves without another invocation. Two creates diffing against one cursor would give two deltas of which only the first could be taken. |
+| `hook_received` | Replay resuming a hook | `eventCount` | The replay continues from the log right after. |
+| `hook_received` | Webhook or `resumeHook()` | Nothing | Out-of-band. It enqueues a delivery that loads the log. |
+| `wait_completed` | Replay completing an elapsed wait | `eventCount` | The replay continues from the log right after. |
+| `step_started`, `step_retrying` | Step executor | Nothing | The executor holds no log. The next decision is a replay that reloads, or receives the delta on the step's terminal write. |
+| `step_completed`, `step_failed` | Step executor | `sinceCursor` when a single step runs inline; nothing from a queued delivery | Inline, this is where the invocation gets its log back without a list. From a queue, a fresh replay loads the log anyway. |
+| `attr_set` | `setAttributes()` outside a workflow | Nothing | Out-of-band. |
+| `run_completed`, `run_failed`, `run_cancelled` | Replay, or `cancel()` | Never `sinceCursor` | Terminal. Nothing replays the log afterwards, so a page would be read by no one. |
+
+Batched writes (`events.createBatch()`) carry no position and get no page. Both runtime engines follow this table: the `node:vm` engine merges a returned page into the log it replays from, and the QuickJS engine queues it for delivery to its live VM, in position order, ahead of its next `events.list()`.
+
+A World that supports this returns the page in `events`, `cursor`, and `hasMore` on the `EventResult`. A World that does not simply returns the created event, and the runtime lists. See [Building a World](/worlds/building-a-world#event-id-allocation) for the World-side contract.
+
 ## Sealed positions (noop events)
 
 Runs at `specVersion` 7 and above use a *sealed log*. The backend gives each write its position from a per-run sequencer **before** the write commits, so concurrent writers hold distinct positions and never race for a slot. New runs use this behavior by default. [`WORKFLOW_SEALED_LOG=0`](/docs/configuration/runtime-tuning#workflow_sealed_log) returns a deployment to the previous scheme. Every runtime reads a sealed log regardless, and a run's version is fixed at creation, so changing the setting never affects an in-flight run. However, a writer can claim a position and then stop because of a crashed process or canceled transaction. This leaves a hole that no writer will fill, and a hole looks like an event the reader failed to load.

package/docs/observability/retention.mdx

@@ -72,7 +72,8 @@ only in how the absence is labelled.
   [`RunExpiredError`](/docs/errors/run-expired) instead of resolving.
 
   This is a known limitation. If you need the result, send it somewhere you
-  control, e.g. a step that writes it to your own store, rather than reading it back off the run.
+  control, e.g. a step that writes it to your own store, rather than reading
+  it back off the run.
 </Callout>
 
 `RunExpiredError` is not specific to `experimental_retention: 0`. Any run read
@@ -86,8 +87,9 @@ missing and you get `WorkflowRunNotFoundError` instead.
 
 The SDK records your preference; it does not enforce it. `start()` writes the
 value onto the run as the reserved `$retention` attribute, and the World
-decides what to do when the run ends.
-A World that does not implement retention
-**keeps the data**. If you need certainty that a specific World deletes your data,
-confirm it against that World's own documentation rather than the presence of this
-option.
+decides what to do when the run ends. Attributes are a spec version 4 feature,
+so `experimental_retention: 0` throws against an older World rather than being
+recorded and ignored. A World that does implement spec version 4 but not
+retention **keeps the data**. If you need certainty that a specific World
+deletes your data, confirm it against that World's own documentation rather
+than the presence of this option.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "workflow",
-  "version": "5.0.0-beta.50",
+  "version": "5.0.0-beta.52",
   "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.0-beta.50",
-    "@workflow/cli": "5.0.0-beta.50",
-    "@workflow/core": "5.0.0-beta.50",
+    "@workflow/astro": "5.0.0-beta.52",
+    "@workflow/cli": "5.0.0-beta.52",
+    "@workflow/core": "5.0.0-beta.52",
     "@workflow/errors": "5.0.0-beta.21",
     "@workflow/typescript-plugin": "5.0.0-beta.5",
     "@workflow/utils": "5.0.0-beta.10",
     "ms": "2.1.3",
-    "@workflow/next": "5.0.0-beta.50",
-    "@workflow/nest": "5.0.0-beta.50",
-    "@workflow/nitro": "5.0.0-beta.50",
-    "@workflow/nuxt": "5.0.0-beta.50",
-    "@workflow/sveltekit": "5.0.0-beta.50",
-    "@workflow/rollup": "5.0.0-beta.50"
+    "@workflow/next": "5.0.0-beta.52",
+    "@workflow/nest": "5.0.0-beta.52",
+    "@workflow/nitro": "5.0.0-beta.52",
+    "@workflow/nuxt": "5.0.0-beta.52",
+    "@workflow/sveltekit": "5.0.0-beta.52",
+    "@workflow/rollup": "5.0.0-beta.52"
   },
   "devDependencies": {
     "@types/ms": "2.1.0",