workflow 5.0.0-beta.46 → 5.0.0-beta.48

package/dist/internal/errors.d.ts

@@ -1,2 +1,2 @@
-export { EntityConflictError, HookConflictError, HookNotFoundError, PreconditionFailedError, RunExpiredError, RunNotSupportedError, StepNotRegisteredError, ThrottleError, TooEarlyError, WorkflowError, WorkflowNotRegisteredError, WorkflowRunCancelledError, WorkflowRunFailedError, WorkflowRunNotCompletedError, WorkflowRunNotFoundError, WorkflowRuntimeError, WorkflowWorldError, } from '@workflow/errors';
+export { EntityConflictError, HookConflictError, HookNotFoundError, PreconditionFailedError, RunExpiredError, RunNotSupportedError, StepNotRegisteredError, StreamError, ThrottleError, TooEarlyError, WorkflowError, WorkflowNotRegisteredError, WorkflowRunCancelledError, WorkflowRunFailedError, WorkflowRunNotCompletedError, WorkflowRunNotFoundError, WorkflowRuntimeError, WorkflowWorldError, } from '@workflow/errors';
 //# sourceMappingURL=errors.d.ts.map

package/dist/internal/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/internal/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,iBAAiB,EACjB,uBAAuB,EACvB,eAAe,EACf,oBAAoB,EACpB,sBAAsB,EACtB,aAAa,EACb,aAAa,EACb,aAAa,EACb,0BAA0B,EAC1B,yBAAyB,EACzB,sBAAsB,EACtB,4BAA4B,EAC5B,wBAAwB,EACxB,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/internal/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,iBAAiB,EACjB,uBAAuB,EACvB,eAAe,EACf,oBAAoB,EACpB,sBAAsB,EACtB,WAAW,EACX,aAAa,EACb,aAAa,EACb,aAAa,EACb,0BAA0B,EAC1B,yBAAyB,EACzB,sBAAsB,EACtB,4BAA4B,EAC5B,wBAAwB,EACxB,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,kBAAkB,CAAC"}

package/dist/internal/errors.js

@@ -1,2 +1,2 @@
-export { EntityConflictError, HookConflictError, HookNotFoundError, PreconditionFailedError, RunExpiredError, RunNotSupportedError, StepNotRegisteredError, ThrottleError, TooEarlyError, WorkflowError, WorkflowNotRegisteredError, WorkflowRunCancelledError, WorkflowRunFailedError, WorkflowRunNotCompletedError, WorkflowRunNotFoundError, WorkflowRuntimeError, WorkflowWorldError, } from '@workflow/errors';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZXJyb3JzLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL2ludGVybmFsL2Vycm9ycy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEVBQ0wsbUJBQW1CLEVBQ25CLGlCQUFpQixFQUNqQixpQkFBaUIsRUFDakIsdUJBQXVCLEVBQ3ZCLGVBQWUsRUFDZixvQkFBb0IsRUFDcEIsc0JBQXNCLEVBQ3RCLGFBQWEsRUFDYixhQUFhLEVBQ2IsYUFBYSxFQUNiLDBCQUEwQixFQUMxQix5QkFBeUIsRUFDekIsc0JBQXNCLEVBQ3RCLDRCQUE0QixFQUM1Qix3QkFBd0IsRUFDeEIsb0JBQW9CLEVBQ3BCLGtCQUFrQixHQUNuQixNQUFNLGtCQUFrQixDQUFDIiwic291cmNlc0NvbnRlbnQiOlsiZXhwb3J0IHtcbiAgRW50aXR5Q29uZmxpY3RFcnJvcixcbiAgSG9va0NvbmZsaWN0RXJyb3IsXG4gIEhvb2tOb3RGb3VuZEVycm9yLFxuICBQcmVjb25kaXRpb25GYWlsZWRFcnJvcixcbiAgUnVuRXhwaXJlZEVycm9yLFxuICBSdW5Ob3RTdXBwb3J0ZWRFcnJvcixcbiAgU3RlcE5vdFJlZ2lzdGVyZWRFcnJvcixcbiAgVGhyb3R0bGVFcnJvcixcbiAgVG9vRWFybHlFcnJvcixcbiAgV29ya2Zsb3dFcnJvcixcbiAgV29ya2Zsb3dOb3RSZWdpc3RlcmVkRXJyb3IsXG4gIFdvcmtmbG93UnVuQ2FuY2VsbGVkRXJyb3IsXG4gIFdvcmtmbG93UnVuRmFpbGVkRXJyb3IsXG4gIFdvcmtmbG93UnVuTm90Q29tcGxldGVkRXJyb3IsXG4gIFdvcmtmbG93UnVuTm90Rm91bmRFcnJvcixcbiAgV29ya2Zsb3dSdW50aW1lRXJyb3IsXG4gIFdvcmtmbG93V29ybGRFcnJvcixcbn0gZnJvbSAnQHdvcmtmbG93L2Vycm9ycyc7XG4iXX0=
+export { EntityConflictError, HookConflictError, HookNotFoundError, PreconditionFailedError, RunExpiredError, RunNotSupportedError, StepNotRegisteredError, StreamError, ThrottleError, TooEarlyError, WorkflowError, WorkflowNotRegisteredError, WorkflowRunCancelledError, WorkflowRunFailedError, WorkflowRunNotCompletedError, WorkflowRunNotFoundError, WorkflowRuntimeError, WorkflowWorldError, } from '@workflow/errors';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZXJyb3JzLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL2ludGVybmFsL2Vycm9ycy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEVBQ0wsbUJBQW1CLEVBQ25CLGlCQUFpQixFQUNqQixpQkFBaUIsRUFDakIsdUJBQXVCLEVBQ3ZCLGVBQWUsRUFDZixvQkFBb0IsRUFDcEIsc0JBQXNCLEVBQ3RCLFdBQVcsRUFDWCxhQUFhLEVBQ2IsYUFBYSxFQUNiLGFBQWEsRUFDYiwwQkFBMEIsRUFDMUIseUJBQXlCLEVBQ3pCLHNCQUFzQixFQUN0Qiw0QkFBNEIsRUFDNUIsd0JBQXdCLEVBQ3hCLG9CQUFvQixFQUNwQixrQkFBa0IsR0FDbkIsTUFBTSxrQkFBa0IsQ0FBQyIsInNvdXJjZXNDb250ZW50IjpbImV4cG9ydCB7XG4gIEVudGl0eUNvbmZsaWN0RXJyb3IsXG4gIEhvb2tDb25mbGljdEVycm9yLFxuICBIb29rTm90Rm91bmRFcnJvcixcbiAgUHJlY29uZGl0aW9uRmFpbGVkRXJyb3IsXG4gIFJ1bkV4cGlyZWRFcnJvcixcbiAgUnVuTm90U3VwcG9ydGVkRXJyb3IsXG4gIFN0ZXBOb3RSZWdpc3RlcmVkRXJyb3IsXG4gIFN0cmVhbUVycm9yLFxuICBUaHJvdHRsZUVycm9yLFxuICBUb29FYXJseUVycm9yLFxuICBXb3JrZmxvd0Vycm9yLFxuICBXb3JrZmxvd05vdFJlZ2lzdGVyZWRFcnJvcixcbiAgV29ya2Zsb3dSdW5DYW5jZWxsZWRFcnJvcixcbiAgV29ya2Zsb3dSdW5GYWlsZWRFcnJvcixcbiAgV29ya2Zsb3dSdW5Ob3RDb21wbGV0ZWRFcnJvcixcbiAgV29ya2Zsb3dSdW5Ob3RGb3VuZEVycm9yLFxuICBXb3JrZmxvd1J1bnRpbWVFcnJvcixcbiAgV29ya2Zsb3dXb3JsZEVycm9yLFxufSBmcm9tICdAd29ya2Zsb3cvZXJyb3JzJztcbiJdfQ==

package/docs/api-reference/workflow-api/resume-hook.mdx

@@ -12,9 +12,11 @@ related:
 
 Resumes a workflow run by sending a payload to a hook identified by its token.
 
-It publishes a workflow invocation carrying the payload; the runtime creates the `hook_received` event and continues execution from it.
+It durably writes the `hook_received` event and only then publishes a workflow wake. The call resolves only after both operations succeed, in that order.
 
-`resumeHook()` throws `HookNotFoundError` when no hook holds the token. A run that has already ended cannot be resumed, including one whose Hook is kept by `experimental_minRetention`, but whether the call reports that depends on the path it takes: a resume dispatched without reading the run resolves and the ended state is only detected once the payload arrives, while one that reads the run, or that falls back to writing the event up front, throws `HookNotFoundError`. See [lazy hook resume](/docs/changelog/lazy-hook-resume).
+`resumeHook()` throws `HookNotFoundError` when no hook holds the token or when its `hook_received` write is refused because the hook was disposed or the run ended. See [durable hook resume](/docs/changelog/lazy-hook-resume).
+
+If `resumeHook()` throws any other error, the outcome is ambiguous only in dispatch, never in durability: the event may already be durable even though the workflow wake failed, and any later wake of the run delivers it. Calling `resumeHook()` again creates a new `resumeId` and can append a second `hook_received`. Callers that need at-most-once behavior across separate invocations must retain and deduplicate their own request key.
 
 <Callout type="warn">
 `resumeHook` is a runtime function that must be called from outside a workflow function.
@@ -50,7 +52,7 @@ showSections={["parameters"]}
 
 ### Returns
 
-Returns a `Promise<ResumedHook>`, a `Hook` extended with an optional `resilientResume` flag. Resolving means the resume was accepted for delivery: the payload rides the workflow queue message and the runtime materializes the `hook_received` event from it before replaying (see the [lazy hook resume changelog](/docs/changelog/lazy-hook-resume)). `resilientResume` is retained for source compatibility and is no longer set by any path. The resolved hook:
+Returns a `Promise<ResumedHook>`, a `Hook` extended with an optional `resilientResume` flag. Resolving means the payload is durably recorded as `hook_received` and the workflow wake was accepted. `resilientResume` is retained for source compatibility and is no longer set by any path. The resolved hook:
 
 <TSDoc
 definition={`

package/docs/api-reference/workflow-api/start.mdx

@@ -108,6 +108,18 @@ The `deploymentId` option is currently a Vercel-specific feature. Other Worlds m
 In Worlds without atomic, immutable deployments (such as local development or self-hosted Postgres), there is no notion of multiple deployments to resolve between, so `deploymentId: "latest"` has no effect: the SDK logs a warning and the run targets the current deployment. This means a workflow that opts into `"latest"` on Vercel still runs unchanged in local development.
 </Callout>
 
+<Callout type="info">
+Resolving `"latest"` is the one `start()` path that calls the Vercel API, so it
+needs an identity that can see the calling deployment. Inside a Vercel
+deployment the SDK authenticates with the deployment's own OIDC token, which
+carries the owning team, and this takes precedence over a `VERCEL_TOKEN` set in
+the function's environment. A `VERCEL_TOKEN` belongs to a *user* and carries no
+team, so authenticating with it scopes the lookup to that user's default team
+and fails with a 404 whenever that is not the team that owns the deployment.
+Outside a deployment (CLI, CI, the dashboard) `VERCEL_TOKEN` is still used;
+configure the World's `teamId` so the request is scoped explicitly.
+</Callout>
+
 <Callout type="warn">
 When using `deploymentId: "latest"`, the workflow run will execute on a potentially different deployment than the one calling `start()`. Be mindful of forward and backward compatibility:
 

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

@@ -2,7 +2,7 @@
 title: Analytics
 description: Metadata-only read APIs for runs, steps, events, hooks, waits, and attributes, backed by the observability pipeline.
 type: reference
-summary: "Interfaces: world.analytics.runs, .attributes, .steps, .events, .hooks, .waits. Metadata-only listings with plan-based lookback windows; filter runs by attribute key=value."
+summary: "Interfaces: world.analytics.runs, .attributes, .steps, .events, .hooks, .waits. Metadata-only listings with plan-based lookback windows; filter runs by attribute key=value. Page limits are 1000 run-scoped, 100 cross-run."
 prerequisites:
   - /docs/api-reference/workflow-runtime/get-world
 related:
@@ -13,7 +13,8 @@ keywords:
   - analytics.runs
   - analytics.attributes
   - attribute filter
-  - listValues
+  - getMany
+  - pagination limit
   - lookback window
   - observability-upgrade-required
   - pageInfo
@@ -22,9 +23,10 @@ keywords:
 
 `world.analytics` is an optional, read-only namespace for observability surfaces: dashboards, command-line interface (CLI) tools, 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.
+Prefer this namespace for observability: listing, filtering, and inspecting
+workflow state. Use the [Storage](/docs/api-reference/workflow-runtime/world/storage)
+API for payload-bearing reads, and for anything operational that has to see the
+canonical, up-to-the-moment record.
 
 It differs from [Storage](/docs/api-reference/workflow-runtime/world/storage) in two ways:
 
@@ -108,19 +110,190 @@ for (const { key, runCount, lastSeenAt } of page.data) {
 
 ---
 
-## analytics.steps, analytics.events, analytics.hooks, analytics.waits
+## analytics.steps
 
-Run-scoped listings mirroring their [Storage](/docs/api-reference/workflow-runtime/world/storage) counterparts, minus payload data:
+Run-scoped step listings mirroring their [Storage](/docs/api-reference/workflow-runtime/world/storage) counterparts, minus payload data.
+
+### steps.list()
+
+```typescript lineNumbers
+const steps = await world.analytics.steps.list({
+  runId,
+  pagination: { limit: 200, sortOrder: "asc" },
+});
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `params.runId` | `string` | Required. The run to list steps for |
+| `params.pagination` | `PaginationOptions` | Cursor pagination, `limit` up to 1000 |
+
+**Returns:** `PaginatedResponse<AnalyticsStep>`. Each step includes `stepId`, `stepName`, `status`, `attempt`, lifecycle timestamps, `errorCode`, and the `computeInstanceId` of the latest attempt.
+
+### steps.get()
+
+```typescript lineNumbers
+const step = await world.analytics.steps.get(runId, stepId);
+```
+
+**Returns:** `AnalyticsStep`. A step id is only unique within its run, so both arguments are required.
+
+---
+
+## analytics.events
+
+### events.list()
+
+```typescript lineNumbers
+const events = await world.analytics.events.list({
+  runId,
+  eventType: "step_failed", // [!code highlight]
+  pagination: { limit: 1000 },
+});
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `params.runId` | `string` | Required. The run to list events for |
+| `params.eventType` | `string` | One event type, for example `run_failed` or `step_retrying` |
+| `params.correlationId` | `string` | Narrow to one entity: a step, hook, wait, or attribute id |
+| `params.pagination` | `PaginationOptions` | Cursor pagination, `limit` up to 1000 |
+
+**Returns:** `PaginatedResponse<AnalyticsEvent>`. Each event includes `eventId`, `eventType`, `correlationId`, `stepName`, `createdAt`, and provenance fields (`region`, `requestId`, `computeInstanceId`).
+
+Pass a step id as `correlationId` to build that step's timeline: `step_created` through `step_completed`, `step_failed`, or `step_retrying`.
+
+### events.get()
+
+```typescript lineNumbers
+const event = await world.analytics.events.get(runId, eventId);
+```
+
+**Returns:** `AnalyticsEvent`.
+
+### events.getMany()
+
+Look up a bounded set of event ids in one run with a single request.
+
+```typescript lineNumbers
+const events = await world.analytics.events.getMany(runId, eventIds); // [!code highlight]
+```
+
+**Returns:** `AnalyticsEvent[]` — not paginated, and no `pageInfo`. Duplicate ids are looked up once, and ids with no analytics row yet are **omitted rather than erroring**, since ingestion can trail canonical storage. Compare the returned length against your input to detect that.
+
+---
+
+## analytics.hooks
+
+### hooks.list()
 
 ```typescript lineNumbers
-const steps = await world.analytics.steps.list({ runId });
-const events = await world.analytics.events.list({ runId, eventType: "step_failed" });
-const related = await world.analytics.events.listByCorrelationId({ runId, correlationId });
 const hooks = await world.analytics.hooks.list({ runId });
-const waits = await world.analytics.waits.list({ runId, status: "waiting" });
 ```
 
-Each namespace also has a `get()` for point lookups (`steps.get(runId, stepId)`, `events.get(runId, eventId)`, `hooks.get(hookId)`, `waits.get(runId, waitId)`). Hook listings never include the hook token. Resolve it separately through the runtime APIs if you need to deliver a payload.
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `params.runId` | `string` | Required. The run to list hooks for |
+| `params.pagination` | `PaginationOptions` | Cursor pagination, `limit` up to 100 |
+
+**Returns:** `PaginatedResponse<AnalyticsHook>`: `hookId`, `status` (`created`, `received`, `disposed`, or `conflict`), `receivedAt`, `disposedAt`, `isWebhook`, `isSystem`.
+
+### hooks.get()
+
+```typescript lineNumbers
+const hook = await world.analytics.hooks.get(hookId);
+```
+
+Unlike steps and waits, a hook id identifies one hook on its own, so no `runId` is needed. Pass `{ runId }` to scope the lookup when you already know it.
+
+<Callout>
+  Hook listings never include the hook token. Resolve it separately through the
+  runtime APIs if you need to deliver a payload.
+</Callout>
+
+---
+
+## analytics.waits
+
+### waits.list()
+
+```typescript lineNumbers
+const waits = await world.analytics.waits.list({
+  runId,
+  status: "waiting", // [!code highlight]
+});
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `params.runId` | `string` | Required. The run to list waits for |
+| `params.status` | `string` | `waiting` or `completed` |
+| `params.pagination` | `PaginationOptions` | Cursor pagination, `limit` up to 1000 |
+
+**Returns:** `PaginatedResponse<AnalyticsWait>`: `waitId`, `status`, `resumeAt`, `completedAt`.
+
+### waits.get()
+
+```typescript lineNumbers
+const wait = await world.analytics.waits.get(runId, waitId);
+```
+
+**Returns:** `AnalyticsWait`. A wait id is only unique within its run, so both arguments are required.
+
+---
+
+## Limits and validation
+
+Arguments are validated in your process before a request goes out. An
+out-of-range or malformed argument throws a `RangeError` naming the bound it
+broke, rather than reaching the backend and coming back as a 400 — which
+matters because analytics is optional and callers commonly wrap it in a
+`try`/`catch`, where a rejected request is easy to mistake for "no data".
+
+### Page limits
+
+`pagination.limit` defaults to 40 everywhere. The maximum depends on whether
+the listing scans within one run or across runs:
+
+| Method | Max `limit` |
+|--------|-------------|
+| `steps.list()`, `events.list()`, `waits.list()` | 1000 |
+| `runs.list()`, `attributes.list()`, `hooks.list()` | 100 |
+
+`events.getMany()` is not paginated; it accepts 1 to 100 event ids per call.
+
+<Callout type="warn">
+  The two page caps differ by a factor of ten, and `hooks.list()` takes the
+  lower one despite being run-scoped. Reusing one page size across listings is
+  the most common way to trip this.
+</Callout>
+
+### Identifiers
+
+Every id is a prefix plus a ULID, and each is checked before the request:
+
+| Parameter | Shape |
+|-----------|-------|
+| `runId` | `wrun_` |
+| `stepId` | `step_` |
+| `eventId` | `evnt_` |
+| `hookId` | `hook_` |
+| `waitId` | `wait_` |
+| `correlationId` | `step_`, `hook_`, `wait_`, or `attr_` |
+
+Step, event, and wait ids are only unique **within** their run, so the methods that take them require a `runId` too. A hook id stands alone.
+
+### Time windows
+
+`startTime` and `endTime` must be supplied **together** and be parseable ISO 8601 timestamps with `startTime` no later than `endTime`. Passing one without the other throws: it used to be dropped silently, which turned a listing you meant to bound into a scan of the whole retention window that looked like a successful answer.
+
+### Attribute filters
+
+`runs.list({ attributes })` accepts 1 to 8 pairs. Keys are 1 to 256 characters; values are at most 256 UTF-8 bytes. Reserved `$`-prefixed keys are valid in a filter even though user code cannot write them.
+
+### Pagination
+
+`cursor` is an opaque token from the previous response; do not construct or parse one. Branch on `hasMore`, not on `cursor` being non-null, and do not change `sortOrder` mid-walk — the cursor encodes the sort position, so reversing it can skip or repeat rows.
 
 ---
 

package/docs/changelog/index.mdx

@@ -12,7 +12,7 @@ Stay up to date with the latest changes to Workflow SDK.
 
 ## 2026
 
-- [Lazy hook resume](/docs/changelog/lazy-hook-resume) (August 2026)
+- [Durable hook resume](/docs/changelog/lazy-hook-resume) (August 2026)
 - [Resilient hook resume](/docs/changelog/resilient-resume) (July 2026)
 - [Eager processing of steps and incremental event replay](/docs/changelog/eager-processing) (March 2026)
 - Serializable AbortController and AbortSignal (March 12, 2026)

package/docs/changelog/lazy-hook-resume.mdx

@@ -1,51 +1,78 @@
 ---
-title: Lazy hook resume
-description: resumeHook() no longer writes hook_received itself. The queue consumer materializes the event from the message, so a resume costs one round trip.
+title: Durable hook resume
+description: resumeHook() durably writes hook_received and only then publishes the workflow wake, so a resolved call can never be lost to a disposal race.
 ---
 
-# Lazy hook resume
+# Durable hook resume
 
 ## Motivation
 
-[Resilient hook resume](/docs/changelog/resilient-resume) made `resumeHook()` write the `hook_received` event and publish the workflow queue message concurrently, with the queue consumer re-ensuring the event from the message's `hookInput` before replay. Both sides then wrote the same event, and a `(runId, resumeId)` constraint collapsed them onto one.
+The previous lazy path published the serialized hook payload on the workflow
+queue and left the queue consumer to create `hook_received`. If the hook was
+disposed after `resumeHook()` returned but before the consumer write committed,
+that write was rejected and the acknowledged queue delivery could not resume the
+workflow: the caller was told the resume succeeded, and it was lost.
 
-Running the two concurrently removed the second round trip from the critical path, but the write itself stayed: every resume still spent a request on an event the consumer was about to write anyway, and the producer still had to classify its outcome (conflict, throttle, terminal run) to decide whether the resume had survived.
-
-This change drops the producer's write entirely. On the lazy path `resumeHook()` publishes the queue message and nothing else.
+`resumeHook()` now resolves only after both the durable event write and the
+workflow wake have succeeded, in that order.
 
 ## Design
 
-- `resumeHook()` publishes one message carrying `hookInput`: the dehydrated payload, a client-minted `resumeId`, the hook token, and a payload digest. It writes no event.
-- The queue consumer materializes `hook_received` from `hookInput` before replay, keyed by `resumeId`. This is the same write it already performed; it is now the only one.
-- The `(runId, resumeId)` constraint still matters: a queue redelivery, or a delivery re-routed for deployment affinity, repeats the write with the same key, and the backend collapses those onto exactly one committed event.
-- **A failed publish fails the resume.** The message carries both the trigger and the only copy of the payload, so `resumeHook()` throws and nothing is persisted for a later delivery to pick up. This replaces the previous rule where a failed event write could still be recovered through the queue.
-- `ResumedHook.resilientResume` is retained on the type but is never set: with a single writer there is no partial outcome to report. The `workflow.hook.resilient_resume` span attribute is likewise no longer emitted.
-- The resume span reports `workflow.hook.resume_strategy: lazy` (previously `parallel`).
-
-## Behavior change: the event is not visible when `resumeHook()` returns
-
-`resumeHook()` used to await its own `hook_received` write, so by the time it resolved the event was in the log. It no longer writes, so **resolving means the message was published, not that the event exists**. The event appears when the run picks the resume up.
-
-Code that reads the run back immediately after resuming now races. The pattern that breaks is a loop that resumes and then looks for the next thing to resume, keying off "this hook has no `hook_received` yet": it can be handed back the hook it just resumed and deliver a second payload to it. Wait for something that implies the run made progress instead. `waitForHook()` in `@workflow/vitest` takes a `notHookId` option for exactly this.
-
-The runtime has one caller that needs the old guarantee. A step that aborts a shared `AbortController` resumes a hook to record the abort in the event log, and that write is an ordering barrier: it must land before the step completes, or the continuation `step_completed` enqueues can dispatch the next step with a stale, non-aborted signal. That path uses an internal durable resume which keeps the eager write and reports `resume_fallback_reason: durable_required`.
-
-Nothing about delivery changes. The payload is on the queue message and reaches the workflow exactly once.
+The dispatch is strictly serial:
+
+1. The hook is resolved by token. An unknown token throws `HookNotFoundError`.
+2. The producer writes `hook_received` durably into the run's event log. A
+   client-minted `resumeId` and payload digest ride the write when the backend
+   supports atomic resume claims, so transport-level retries of the same write
+   converge on exactly one committed event. A write refused because the hook
+   was disposed or the run ended throws `HookNotFoundError`.
+3. Only after the write is acknowledged does the producer publish the workflow
+   wake. The wake carries no payload — the payload lives in the event log — so
+   nothing rides on the queue message but the trigger. Publication is retried
+   a bounded number of times.
+
+Because the event is committed before the wake exists, a disposal or run
+completion racing the queue delivery cannot erase a resume the caller was told
+succeeded: the delivery replays the committed event from the log.
+
+- `ResumedHook.resilientResume` remains on the type for source compatibility
+  and is no longer set. The internal `resumeHookDurable()` entry point is
+  removed; `resumeHook()` itself now provides the durable guarantee.
+
+A resolved call proves that the event is durable and the wake was accepted.
+`HookNotFoundError` proves this invocation committed no event. Any other thrown
+error is ambiguous only in *dispatch*, never in durability: a wake failure
+after the write leaves the event committed, and any later wake of the run
+(from any source) delivers it. A fresh `resumeHook()` invocation mints a new
+`resumeId`, so blindly retrying a failed call can append a second
+`hook_received`; callers that need at-most-once behavior across separate
+invocations must deduplicate on their own request key.
 
 ## Behavior change: resumes against an ended run
 
-The hook lookup is unchanged: `resumeHook(token, ...)` still resolves the token through `hooks.getByToken()`, which throws `HookNotFoundError` when no hook holds it. Hook existence, and the token's binding to a run, are still validated before anything is published.
-
-What the lookup does not carry is the run's *mutable* status. `HookResumeContext` is deliberately an immutable slice of the run, so a resume that runs off it never learns whether the run is still live. That used to be caught by the `hook_received` write being rejected. With no write, **a resume against an ended run resolves instead of throwing `HookNotFoundError`**.
-
-This is only reachable when the hook record outlives its run, since otherwise the lookup itself fails: a hook kept by `experimental_minRetention`, or one whose token has not been released yet. Resumes that fall back to reading the run keep their terminal pre-check, as does the sequential path, so a resume on either of those still fails loudly.
+The lazy path never observed the server's rejection — it published a message
+and resolved, so a resume against a run that had already ended reported
+success (reachable whenever the hook record outlives its run, e.g. token
+retention). The durable write restores the check: **a resume against an ended
+run now throws `HookNotFoundError`**, and a late webhook delivery to a
+finished run answers 404 where it previously answered 202. Senders that treat
+4xx as terminal will stop retrying such deliveries; that is the correct
+signal, since nothing can resume an ended run.
 
-Nothing resumes either way. The consumer's write is rejected the same way and the delivery is consumed, so the ended run is untouched. Only the producer's report changes: an accepted publish means the resume was dispatched, not that the run was still live when it arrived. A [webhook](/docs/api-reference/workflow-api/resume-webhook) whose run has ended can answer `202` rather than surfacing an error.
-
-Callers that need the distinction have to read the run.
+A transient write conflict (HTTP 409, e.g. an event-slot conflict that
+escaped the server's internal retry budget under contention) is no longer
+re-keyed to `HookNotFoundError`. It surfaces as a retryable error, and its
+rejected transaction committed nothing, so retrying the resume is safe.
 
 ## Compatibility
 
-The gating is unchanged: the lazy path activates only when the target run's queue consumer and the live backend both attest support, re-checked on every resume. Oversized payloads, legacy runs, non-CBOR transports, and `WORKFLOW_DISABLE_LAZY_HOOK_RESUME=1` fall back to the sequential write-then-publish path.
+Nothing about the queue message changes: the wake has the same shape the
+sequential path always published, so no consumer, backend, or server
+coordination is needed and either side can roll back independently.
+
+Consumers continue to accept legacy `hookInput` messages from older producers,
+materializing their payload before replay. This permits rolling upgrades
+without a coordinated producer and consumer deployment.
 
-Consumers still accept a message from an older producer that wrote the event itself: such a message reports `strategy: parallel`, and the consumer's write converges on the producer's committed event exactly as before. No coordinated deploy is needed in either direction.
+`WORKFLOW_DISABLE_LAZY_HOOK_RESUME` no longer gates anything and is ignored:
+there is no lazy path left to disable.

package/docs/changelog/resilient-resume.mdx

@@ -6,11 +6,13 @@ description: resumeHook() now tolerates transient event storage failures when th
 # Resilient `resumeHook()`
 
 <Callout type="info">
-  Superseded by [lazy hook resume](/docs/changelog/lazy-hook-resume):
-  `resumeHook()` no longer writes the `hook_received` event at all on the fast
-  path, so the two-writer design and the `resilientResume` flag described below
-  are historical. The `(runId, resumeId)` constraint and the queue-carried
-  payload remain.
+  Superseded by [durable hook resume](/docs/changelog/lazy-hook-resume):
+  `resumeHook()` now writes the `hook_received` event durably and only then
+  publishes the workflow wake, so the two-writer design, the queue-carried
+  payload, and the `resilientResume` flag described below are historical. The
+  `(runId, resumeId)` constraint remains, converging transport-level retries
+  of the producer's own write (and legacy `hookInput` redeliveries from older
+  producers).
 </Callout>
 
 ## Motivation
@@ -27,4 +29,4 @@ description: resumeHook() now tolerates transient event storage failures when th
 
 ## Compatibility
 
-The parallel fast path is gated per resume: it activates only when both the target run's queue consumer and the live backend independently attest dedup support (re-checked on every resume, so rollout and rollback both degrade safely). Otherwise (for oversized payloads, legacy runs, or with `WORKFLOW_DISABLE_LAZY_HOOK_RESUME=1`), `resumeHook()` falls back to the original sequential write-then-dispatch path. Because runs keep executing on the deployment they were created on, a resume targeting a run from an older deployment uses the sequential path.
+The parallel fast path is gated per resume: it activates only when both the target run's queue consumer and the live backend independently attest dedup support (re-checked on every resume, so rollout and rollback both degrade safely). Otherwise (for oversized payloads or legacy runs), `resumeHook()` falls back to the original sequential write-then-dispatch path. Because runs keep executing on the deployment they were created on, a resume targeting a run from an older deployment uses the sequential path.

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

@@ -94,14 +94,14 @@ Vercel project and auth settings can often be inferred from `.vercel/project.jso
 ### `--sort`
 
 - Environment variable: none
-- Default: `desc`
+- Default: `desc` for time-ordered listings; `workflow inspect attributes` orders keys alphabetically unless you pass this flag
 - Sort order for list commands. Accepts `asc` or `desc`.
 
 ### `--limit`
 
 - Environment variable: none
 - Default: `20`
-- Number of items returned per page for list commands.
+- Number of items returned per page for list commands. `workflow cancel` bounds it separately; see [`--limit` (cancel)](#--limit-cancel).
 
 ### `--cursor`
 
@@ -115,6 +115,63 @@ Vercel project and auth settings can often be inferred from `.vercel/project.jso
 - Default: disabled
 - Enables keyboard-controlled pagination for supported list commands.
 
+## Inspect filtering
+
+Flags for `workflow inspect`. Each list view accepts a different subset, noted
+per flag.
+
+### `--runId` / `-r`
+
+- Command: `workflow inspect`
+- Default: unset
+- Scopes the listing to one run. Required for `steps`, `events`, and `sleeps`; optional for `hooks`. Must be a run ID: `wrun_` followed by a 26-character ULID.
+
+### `--limit` (inspect)
+
+- Command: `workflow inspect`
+- Default: `20`
+- Must be an integer between 1 and 100, the smallest page any inspect listing accepts. Larger pages are reachable by paging: pass `--cursor`, or `--interactive` to walk them.
+
+### `--stepId` / `-s`
+
+- Command: `workflow inspect events`
+- Default: unset
+- Filters events to one step.
+
+### `--hookId`
+
+- Command: `workflow inspect events`
+- Default: unset
+- Filters events to one hook.
+
+### `--attribute`
+
+- Command: `workflow inspect runs`
+- Default: unset
+- Filters runs to those whose [attributes](/docs/observability/attributes) match every `key=value` pair given. Repeatable up to 8 times, and splits on the first `=` so a value may contain one.
+- Requires a backend with the analytics read path; ignored with a warning otherwise.
+- Cannot be combined with `--url` or `--web`, which hand off to the dashboard, or with `--withData`, which reads payloads from storage. Storage carries no attribute index.
+- Use `workflow inspect attributes` to discover which keys exist.
+
+### `--since` / `--until`
+
+- Command: `workflow inspect runs`, `workflow inspect attributes`
+- Default: the backend's own window
+- Bounds the listing to a window. `--since` opens the window and accepts a relative duration (`30m`, `12h`, `7d`, `2w`) or a timestamp. `--until` is optional and defaults to now, so `--until` on its own is rejected.
+- Requires a backend with the analytics read path; ignored with a warning otherwise.
+
+### `--withData` / `-d`
+
+- Command: `workflow inspect`
+- Default: disabled
+- Includes full input and output payloads in list views. Deprecated for list views — use `workflow inspect <resource> <id>` to read one item's payloads. Setting it also moves the read off the analytics path, which carries metadata only.
+
+### `--decrypt`
+
+- Command: `workflow inspect`
+- Default: disabled
+- Decrypts encrypted values. Triggers an audit-logged key retrieval.
+
 ## Bulk cancel
 
 `workflow cancel <run-id>` cancels one run. Given a filter instead, it bulk-cancels a batch; bulk mode requires `--status` or `--workflowName`.
@@ -124,18 +181,20 @@ Vercel project and auth settings can often be inferred from `.vercel/project.jso
 - Command: `workflow cancel`
 - Default: unset
 - Restricts the batch to this status. Only `pending` and `running` are accepted; terminal runs cannot be canceled.
+- Also filters `workflow inspect runs`, which accepts any run status. It does not narrow `workflow inspect attributes`, which indexes keys per tenant rather than per run; passing it there warns and lists every key.
 
 ### `--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.
+- Also filters `workflow inspect runs` and `workflow inspect attributes`.
 
 ### `--limit` (cancel)
 
 - Command: `workflow cancel`
 - Default: `50`
-- Maximum runs to cancel in one batch (1–500). Only one batch is canceled per invocation; run the command again to cancel the next batch.
+- Maximum runs to cancel in one batch (1–100), the largest page the run listing serves. Only one batch is canceled per invocation; run the command again to cancel the next batch.
 
 ### `--confirm` / `-y`
 

package/docs/configuration/runtime-tuning.mdx

@@ -81,14 +81,6 @@ For example, a workflow can run a 10-minute inline step even with `WORKFLOW_REPL
 - 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 publishes the workflow invocation and writes no event, so the resume costs one round trip. The queue message carries the payload, and the consumer creates the `hook_received` event from it before replay. A backend `(runId, resumeId)` constraint keeps redeliveries of that message converging on exactly one event. Because the message is the only copy of the payload, a failed publish fails the resume.
-- The runtime falls back to the sequential path 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 two paths differ on ended runs: the sequential write is rejected and surfaces as `HookNotFoundError`, while the lazy path resolves because it never writes. Neither resumes the run.
-- 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`
@@ -100,7 +92,7 @@ For example, a workflow can run a 10-minute inline step even with `WORKFLOW_REPL
 ### `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 lazy hook resume (`hookInput`).
+- 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`.
@@ -193,10 +185,10 @@ For example, a workflow can run a 10-minute inline step even with `WORKFLOW_REPL
 ### `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.
-- A step-driven suspension can keep the VM retained even when hooks are open or created at the same boundary. Hook-only suspensions park the invocation. Suspensions involving waits or attributes, runs with an open wait, and any replay divergence fall back to a full replay.
+- 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 from scratch in a fresh VM on every iteration.
+- Set `0` or `false` to replay the Node.js workflow from scratch in a fresh VM on every iteration.
 
 ### `WORKFLOW_INLINE_OWNERSHIP`
 

package/docs/errors/corrupted-event-log.mdx

@@ -1,37 +1,46 @@
 ---
 title: corrupted-event-log
-description: The workflow's event log contains an event that no consumer can process, indicating corruption or invalid state.
+description: The workflow's event log contains an event that cannot be processed or a stored payload that cannot be read.
 type: troubleshooting
-summary: Resolve corrupted event log errors caused by orphaned or unattributable events.
+summary: Resolve corrupted event log errors caused by invalid events or unreadable stored payloads.
 prerequisites:
   - /docs/foundations/workflows-and-steps
 related:
   - /docs/foundations/errors-and-retries
 ---
 
-This error occurs when the Workflow runtime repeatedly cannot replay events in the event log. This usually means the event log is in an invalid state, such as an orphaned event or one no consumer can attribute to anything the workflow did, or that a runtime determinism bug persists across retry attempts.
+This error occurs when the Workflow runtime cannot safely replay the event log. The log may be in an invalid state, such as an orphaned event or one no consumer can attribute to anything the workflow did, or it may reference a stored payload that the World can no longer read.
 
-This is a **workflow-level fatal error**. It cannot be caught or handled inside your workflow code. The runtime first retries transient replay divergence automatically; it marks the run as failed with this error only after replay still cannot recover.
+This is a **workflow-level fatal error**. It cannot be caught or handled inside your workflow code. The runtime retries transient replay divergence automatically, but an unreadable stored payload is terminal immediately because replaying cannot restore it.
 
 ## Error message
 
+For replay divergence:
+
 ```text
 Workflow replay diverged <divergenceCount> times after <maxRecoveryReplays> recovery replays; latest divergent event was <eventId>. Last divergence: <details>
 ```
 
+For an unreadable stored payload:
+
+```text
+the event log references a payload that no longer exists in storage: <details>
+```
+
 ## Why this happens
 
 Workflows persist their progress as an ordered event log. During replay, the runtime processes each event in sequence. Every event must be consumed by a matching callback, such as a step or sleep waiting for its result. An event no callback ever claims is one the runtime would have to drop to finish the run, so it fails the run instead of returning a result that silently ignored it.
 
 A delivery written from outside the replay, such as a hook firing or a step completing on another invocation, can land ahead of the events the replay is writing itself. That is ordinary concurrency rather than corruption, so the runtime holds such an event and offers it to each consumer the replay registers afterwards. The failure comes only when the workflow function returns while an event is still held, at which point no consumer can ever appear. A replay that suspends still holding one reports it on the span (`workflow.events.parked.count`, `.event_id`, `.event_type`) and leaves the decision to the replay that follows.
 
-Before failing, the runtime retries a divergent replay and surfaces this terminal error only if replay still cannot recover.
+Before failing on divergence, the runtime retries the replay and surfaces this terminal error only if replay still cannot recover. It does not retry a payload that the World reports as permanently missing.
 
 Common scenarios that produce this error:
 
 - **An unclaimed event that repeats nothing**: A duplicate of a kind the log already records for that entity is read past rather than failing the run, so a second `step_completed` or `wait_completed` is not this error (see [Duplicate Events](/docs/how-it-works/event-sourcing#duplicate-events)). What fails is an unclaimed event with no earlier counterpart to defer to: a `step_started` behind a `step_completed` on a log that never recorded a `step_started`, for instance. No consumer remains for the step, and there is no earlier event of that kind the replay could be reading instead.
 - **Orphaned events**: A `step_completed` or `wait_completed` event whose `correlationId` doesn't match any step or sleep in the workflow code, so the replay reaches its end still holding it.
 - **A hole in the log**: Events are numbered by their position in the run's log, and those positions are dense, so a position below the log's highest that holds no event means the log the replay loaded is incomplete. The runtime cannot tell a position no write ever occupied from one whose event it failed to read, so it refuses to replay rather than produce a result that may be silently wrong. See [`WORKFLOW_SLOT_GAP_CHECK`](/docs/configuration/runtime-tuning#workflow_slot_gap_check).
+- **An unreadable stored payload**: An event row still references a payload object, but the World reports that the object no longer exists in its storage. The same log would fail on every replay, so the run fails immediately instead of retrying forever.
 
 ## What to do
 
@@ -47,7 +56,7 @@ npm install workflow@latest
 
 ### 2. Retry the failed run
 
-If this error is displayed, automatic replay recovery has already been exhausted and the run has been marked as `failed`. You can re-run it using the **Re-run** button in the Workflow Dashboard.
+If this error reports replay divergence, automatic replay recovery has already been exhausted. If it reports an unreadable payload, recovery cannot recreate that payload. In either case, the run has been marked as `failed`. You can re-run the workflow using the **Re-run** button in the Workflow Dashboard; a re-run starts a new run with a new event log.
 
 ### 3. Report the issue
 
@@ -55,7 +64,7 @@ If the error persists after upgrading, [open an issue on GitHub](https://github.
 
 - The version of the `workflow` package you are using
 - The run ID(s) of the affected workflow run(s)
-- The error message (including `eventType`, `correlationId`, and `eventId`)
+- The complete error message, including any `eventType`, `correlationId`, `eventId`, or payload details
 - Any details about the event log or the workflow that triggered the error
 
 ## This error cannot be caught

package/docs/foundations/errors-and-retries.mdx

@@ -195,7 +195,7 @@ try {
 | `MAX_DELIVERIES_EXCEEDED` | The run exceeded the maximum number of queue deliveries |
 | `REPLAY_TIMEOUT` | A workflow replay exceeded the maximum allowed duration |
 | `REPLAY_DIVERGENCE` | A replay could not consume the event log deterministically, usually because of non-deterministic workflow code. |
-| `CORRUPTED_EVENT_LOG` | The event log contains orphaned or mismatched events and cannot be replayed. If you see this, please [file an issue](https://github.com/vercel/workflow/issues) |
+| `CORRUPTED_EVENT_LOG` | The event log cannot be replayed: it contains orphaned or mismatched events, or one of its stored payloads is no longer readable from the World's storage. If you see this, please [file an issue](https://github.com/vercel/workflow/issues) |
 | `WORLD_CONTRACT_ERROR` | A World response violated the SDK contract; points at a World implementation bug |
 | `RUNTIME_ERROR` | An internal runtime error. If you see this, please [file an issue](https://github.com/vercel/workflow/issues) |
 

package/docs/getting-started/python.mdx

@@ -11,23 +11,23 @@ related:
 ---
 
 <CopyPrompt
-  text="In this Python project, add `requires-python = &quot;&gt;=3.12&quot;` and `dependencies = [&quot;vercel&quot;]` under `[project]` in `pyproject.toml`. 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/workflows/ai_content_workflow.py` importing `wf`, define `@wf.workflow async def ai_content_workflow(*, topic: str)`, and call step functions such as `generate_draft` and `summarize_draft`. Export `wf` from `app/workflows/__init__.py` and import the workflow module so its definitions are registered. Mark step functions with `@wf.step`, use `await workflow.sleep(&quot;7 days&quot;)` for durable delays where needed, and use a `workflow.BaseHook` Pydantic model plus `.wait(token=...)` and `.resume(token)` for external approval events. Verify the workflow entrypoint uses the `module:object` format and points to the exported `Workflows` registry."
+  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)`."
 />
 
 <Callout type="warn">
-The Python SDK is currently in **beta**. APIs and behavior may change. For the latest documentation and updates, see the [official Vercel Workflow Python documentation](https://vercel.com/docs/workflows/python).
+The Python SDK is currently in **beta**. APIs and behavior may change.
 </Callout>
 
-You can build durable workflows in Python using the [`vercel` Python SDK](https://pypi.org/project/vercel/). Your workflow code can pause, resume, and maintain state, just like the JavaScript and TypeScript Workflow SDK.
+You can build durable workflows in Python using the [`vercel-workflow` SDK](https://pypi.org/project/vercel-workflow/). Your workflow code can pause, resume, and maintain state, just like the JavaScript and TypeScript Workflow SDK.
 
 ## Getting started
 
-Add the `vercel` package and workflow entrypoint to `pyproject.toml`:
+Add the `vercel-workflow` package and workflow entrypoint to `pyproject.toml`:
 
 ```toml filename="pyproject.toml"
 [project]
 requires-python = ">=3.12"
-dependencies = ["vercel"]
+dependencies = ["vercel-workflow"]
 
 [[tool.vercel.workflows]]
 entrypoint = "app.workflows:wf"
@@ -39,16 +39,17 @@ The workflow `entrypoint` uses the `module:object` format and points to the expo
 
 A workflow is a stateful function that coordinates multi-step logic over time. Create a `Workflows` instance and use the `@wf.workflow` decorator to mark a function as durable:
 
-```python filename="app/workflow.py" {3}
+```python filename="app/workflow.py"
 from vercel import workflow
 
-wf = workflow.Workflows()
+wf = workflow.Workflows()  # [!code highlight]
 ```
 
-```python filename="app/workflows/ai_content_workflow.py" {3}
+```python filename="app/workflows/ai_content_workflow.py"
 from app.workflow import wf
+from app.steps.generate_draft import generate_draft, summarize_draft
 
-@wf.workflow
+@wf.workflow  # [!code highlight]
 async def ai_content_workflow(*, topic: str):
     draft = await generate_draft(topic=topic)
     summary = await summarize_draft(draft=draft)
@@ -74,15 +75,15 @@ Under the hood, the workflow compiles into a route that orchestrates execution.
 
 A step is a stateless function that runs a unit of durable work inside a workflow. Use `@wf.step` to mark a function as a step:
 
-```python filename="app/steps/generate_draft.py" {4,8}
+```python filename="app/steps/generate_draft.py"
 import random
 from app.workflow import wf
 
-@wf.step
+@wf.step  # [!code highlight]
 async def generate_draft(*, topic: str):
     return await ai_generate(prompt=f"Write a blog post about {topic}")
 
-@wf.step
+@wf.step  # [!code highlight]
 async def summarize_draft(*, draft: str):
     summary = await ai_summarize(text=draft)
 
@@ -95,18 +96,42 @@ 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.
 
+## 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:
+
+```python filename="app/api/generate.py"
+from app.workflows.ai_content_workflow import ai_content_workflow
+from vercel import workflow
+
+@app.post("/api/generate")
+async def generate_content(*, topic: str):
+    run = await workflow.start(ai_content_workflow, topic=topic)  # [!code highlight]
+
+    print(run.run_id)
+    print(await run.status())  # [!code highlight]
+
+    # Wait until the workflow completes and return its result.
+    return await run.return_value()  # [!code highlight]
+```
+
+Starting a workflow only waits until the run has been created and queued. Await `return_value()` to wait for the workflow to finish, or save its `run_id` and recreate the handle later with `workflow.Run(run_id)`.
+
 ## Sleep
 
 Sleep pauses a workflow for a specified duration without consuming compute resources:
 
-```python filename="app/workflows/ai_refine.py" {7}
+```python filename="app/workflows/ai_refine.py"
+from datetime import timedelta
+
+from app.workflow import wf
 from vercel import workflow
 
 @wf.workflow
 async def ai_refine_workflow(*, draft_id: str):
     draft = await fetch_draft(draft_id)
 
-    await workflow.sleep("7 days")  # Wait 7 days to gather more signals.
+    await workflow.sleep(timedelta(days=7))  # Wait 7 days to gather more signals.  # [!code highlight]
 
     refined = await refine_draft(draft)
 
@@ -116,7 +141,31 @@ async def ai_refine_workflow(*, draft_id: str):
     }
 ```
 
-The sleep call pauses the workflow and consumes no resources. The workflow resumes automatically when the time expires.
+The parameter accepts four forms:
+
+| Form | Description | Example |
+| --- | --- | --- |
+| `str` | Human-readable duration string | `"2 days"`, `"1w"`, `"1h 30m"` |
+| `int` or `float` | Seconds from now | `5` (5 seconds) |
+| `datetime.timedelta` | Duration from now | `timedelta(days=7)` |
+| `datetime.datetime` | Absolute wake-up time (must be timezone-aware) | `datetime(2025, 1, 1, tzinfo=UTC)` |
+
+The string form accepts one or more `<value><unit>` pairs. Supported units:
+
+| Duration | Unit |
+| --- | --- |
+| Milliseconds | `ms` |
+| Seconds | `s`, `second`, `seconds` |
+| Minutes | `m`, `minute`, `minutes` |
+| Hours | `h`, `hour`, `hours` |
+| Days | `d`, `day`, `days` |
+| Weeks | `w`, `week`, `weeks` |
+
+<Callout>
+`sleep()` must be called from the workflow body, not from inside a step. Calling it from a step raises a `RuntimeError`.
+</Callout>
+
+The sleep consumes no resources. The workflow resumes automatically when the time expires.
 
 ## Hooks
 
@@ -124,13 +173,17 @@ A hook lets a workflow wait for external events such as user actions, webhooks,
 
 Define a hook model with Pydantic and `workflow.BaseHook`:
 
-```python filename="app/workflows/approval.py" {3,14}
+```python filename="app/workflows/approval.py"
+import typing
+
+import pydantic
+from app.workflow import wf
 from vercel import workflow
 
-class Approval(BaseModel, workflow.BaseHook):
+class Approval(pydantic.BaseModel, workflow.BaseHook):  # [!code highlight]
     """Human approval for AI-generated drafts"""
 
-    decision: Literal["approved", "changes"]
+    decision: typing.Literal["approved", "changes"]
     notes: str | None = None
 
 @wf.workflow
@@ -138,7 +191,7 @@ async def ai_approval_workflow(*, topic: str):
     draft = await generate_draft(topic=topic)
 
     # Wait for human approval events
-    async for event in Approval.wait(token="draft-123"):
+    async for event in Approval.wait(token="draft-123"):  # [!code highlight]
         if event.decision == "approved":
             await publish_draft(draft)
             break
@@ -149,20 +202,56 @@ async def ai_approval_workflow(*, topic: str):
 
 Resume the workflow when data arrives:
 
-```python filename="app/api/resume.py" {5}
+```python filename="app/api/resume.py"
+from app.workflows.approval import Approval
+
 @app.post("/api/resume")
-async def resume(approval: Approval):
+async def resume(approval: Approval):  # [!code highlight]
     """Resume the workflow when an approval is received"""
 
-    await approval.resume("draft-123")
+    await approval.resume("draft-123")  # [!code highlight]
     return {"ok": True}
 ```
 
 When a hook receives data, the workflow resumes automatically. You don&apos;t need polling, message queues, or manual state management.
 
-## Learn more
+## 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:
+
+```python filename="app/workflows/streaming.py"
+from app.workflow import wf
+from vercel import workflow
+
+@wf.step
+async def write_progress():
+    writable = workflow.get_writable()  # [!code highlight]
+
+    for message in ["Drafting", "Reviewing", "Complete"]:
+        await writable.write(message)  # [!code highlight]
+
+    await writable.close()
+
+@wf.workflow
+async def streaming_workflow():
+    await write_progress()
+```
+
+Read the values from the returned `Run` as they arrive:
+
+```python filename="app/api/stream.py"
+from app.workflows.streaming import 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)
+```
 
-For comprehensive documentation, examples, and the latest updates, visit the [official Vercel Workflow Python documentation](https://vercel.com/docs/workflows/python).
+Streams are not closed automatically. Close the writable in the last step that writes to it so readers know when the stream is complete.
 
 ## Next steps
 

package/docs/observability/attributes.mdx

@@ -11,7 +11,7 @@ related:
   - /docs/api-reference/workflow-errors/workflow-world-error
 ---
 
-[`setAttributes`](/docs/api-reference/workflow/set-attributes) attaches plaintext string metadata to the current workflow run. These attributes appear in the Workflow CLI and web UI, and you can use them to search and filter runs through the [Analytics API](/docs/api-reference/workflow-runtime/world/analytics).
+[`setAttributes`](/docs/api-reference/workflow/set-attributes) attaches plaintext string metadata to the current workflow run. These attributes appear in the Workflow CLI and web UI, and you can search and filter runs by them from either the [CLI](#from-the-cli) or the [Analytics API](/docs/api-reference/workflow-runtime/world/analytics).
 
 You can also seed any attributes directly when starting a run:
 
@@ -82,6 +82,28 @@ Expanding an `attr_set` event (in the run sidebar or the Events tab) shows the c
 
 ## Searching and filtering by attributes
 
+### From the CLI
+
+`workflow inspect attributes` lists the keys recorded on this project's runs,
+with how many runs carry each and when it was first and last seen:
+
+```bash
+workflow inspect attributes
+```
+
+Pass one or more `--attribute key=value` pairs to `inspect runs` to list the
+runs carrying them. Repeatable up to 8 times:
+
+```bash
+workflow inspect runs --attribute phase=received --status running
+```
+
+Both require a backend with the analytics read path. `--attribute` is ignored
+with a warning on backends without one, and `inspect attributes` reports that
+it is unavailable.
+
+### From the Analytics API
+
 The [Analytics API](/docs/api-reference/workflow-runtime/world/analytics) can discover which attribute keys exist and filter run listings by them. The `analytics` namespace is optional on `World`, so feature-detect it before use; it is absent on local, Postgres, and other custom Worlds:
 
 ```typescript lineNumbers

package/docs/whats-new.mdx

@@ -33,7 +33,7 @@ The largest change in v5 has no API surface: the runtime does far less work per
 
 **The runtime avoids waiting on the persistence layer where it can determine that is safe for your workload.** The runtime skips many API calls when they aren't needed, such as requesting the event log on a run's first invocation. Step creation is folded into step execution rather than being its own round trip. The inline loop consumes the event-log delta from the previous step's write instead of re-listing events. Each optimization is gated on specific runtime conditions and can be turned off individually. See [Runtime tuning](/docs/configuration/runtime-tuning).
 
-**The workflow VM is kept alive across inline steps.** Within one invocation, a step-driven suspension keeps the live VM and hydrated state, including when hooks are open or created at the same boundary, so the next iteration appends only the newly written events instead of rebuilding the sandbox and replaying the whole log. Step inputs made of plain data or standard built-ins keep this fast path; see [`WORKFLOW_RETAINED_VM`](/docs/configuration/runtime-tuning#workflow_retained_vm).
+**The workflow VM is kept alive across inline steps.** Within one invocation, a step- or attribute-driven suspension keeps the live VM and hydrated state, including when hooks or waits are open or created at the same boundary, so the next iteration appends only the newly written events instead of rebuilding the sandbox and replaying the whole log. Step inputs made of plain data or standard built-ins keep this fast path; see [`WORKFLOW_RETAINED_VM`](/docs/configuration/runtime-tuning#workflow_retained_vm).
 
 **Resuming a hook takes one round trip instead of two.** `resumeHook()` writes the `hook_received` event and dispatches the queue message concurrently, with a `(runId, resumeId)` dedup constraint keeping the two writers converging on exactly one event. See [Resilient hook resumption](/docs/changelog/resilient-resume).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "workflow",
-  "version": "5.0.0-beta.46",
+  "version": "5.0.0-beta.48",
   "description": "Workflow SDK - Build durable, resilient, and observable workflows",
   "main": "dist/typescript-plugin.cjs",
   "type": "module",
@@ -58,25 +58,25 @@
     }
   },
   "dependencies": {
-    "ms": "2.1.3",
-    "@workflow/astro": "5.0.0-beta.46",
-    "@workflow/cli": "5.0.0-beta.46",
-    "@workflow/core": "5.0.0-beta.46",
-    "@workflow/errors": "5.0.0-beta.18",
+    "@workflow/astro": "5.0.0-beta.48",
+    "@workflow/cli": "5.0.0-beta.48",
+    "@workflow/core": "5.0.0-beta.48",
+    "@workflow/errors": "5.0.0-beta.20",
     "@workflow/typescript-plugin": "5.0.0-beta.5",
-    "@workflow/utils": "5.0.0-beta.9",
-    "@workflow/next": "5.0.0-beta.46",
-    "@workflow/nest": "5.0.0-beta.46",
-    "@workflow/nitro": "5.0.0-beta.46",
-    "@workflow/nuxt": "5.0.0-beta.46",
-    "@workflow/sveltekit": "5.0.0-beta.46",
-    "@workflow/rollup": "5.0.0-beta.46"
+    "@workflow/utils": "5.0.0-beta.10",
+    "ms": "2.1.3",
+    "@workflow/next": "5.0.0-beta.48",
+    "@workflow/nest": "5.0.0-beta.48",
+    "@workflow/nitro": "5.0.0-beta.48",
+    "@workflow/nuxt": "5.0.0-beta.48",
+    "@workflow/sveltekit": "5.0.0-beta.48",
+    "@workflow/rollup": "5.0.0-beta.48"
   },
   "devDependencies": {
     "@types/ms": "2.1.0",
     "@types/node": "22.19.0",
-    "typescript": "^6.0.3",
-    "@workflow/tsconfig": "5.0.0-beta.0"
+    "@workflow/tsconfig": "5.0.0-beta.0",
+    "typescript": "^6.0.3"
   },
   "peerDependencies": {
     "@opentelemetry/api": "1"