workflow 5.0.0-beta.13 → 5.0.0-beta.15

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

@@ -0,0 +1,48 @@
+---
+title: workflow
+description: Configure Vite and Nitro to transform workflow directives.
+type: reference
+summary: Add the workflow plugin to your Vite config to enable workflow directive transformation in Vite + Nitro apps.
+prerequisites:
+  - /docs/getting-started/vite
+---
+
+Returns the Vite plugins that transform workflow code (`"use step"`/`"use workflow"` directives) and configure the [`workflow/nitro`](/docs/api-reference/workflow-nitro) module on the Nitro server. It is designed to be used alongside `nitro()` from `nitro/vite`, which provides the server framework for API routes and deployment.
+
+## Usage
+
+To enable `"use step"` and `"use workflow"` directives while developing locally or deploying to production, add `workflow()` to the `plugins` array of your Vite config, together with `nitro()`.
+
+```typescript title="vite.config.ts" lineNumbers
+import { nitro } from "nitro/vite";
+import { defineConfig } from "vite";
+import { workflow } from "workflow/vite"; // [!code highlight]
+
+export default defineConfig({
+  plugins: [nitro(), workflow()], // [!code highlight]
+  nitro: {
+    serverDir: "./",
+  },
+});
+```
+
+## API Signature
+
+### Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `options` | `ModuleOptions` | Optional. Forwarded to the `workflow/nitro` module as its module options. |
+
+#### ModuleOptions
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `dirs` | `string[]` | — | Directories to scan for workflows and steps. By default, the `workflows/` directory is scanned from the project root and all layer source directories. |
+| `typescriptPlugin` | `boolean` | `false` | Adds the `workflow` TypeScript plugin to the generated `tsconfig.json` for IDE IntelliSense. |
+| `runtime` | `string` | — | Node.js runtime version for Vercel Functions (e.g. `'nodejs22.x'`, `'nodejs24.x'`). Only applies when deploying to Vercel. |
+| `sourcemap` | `boolean \| 'inline' \| 'linked' \| 'external' \| 'both'` | `'inline'` | Controls source maps on generated workflow bundles. Accepts the same values as esbuild's `sourcemap` option. Set to `false` for smaller function bundles (useful for staying under the Vercel 250MB function size limit) at the cost of stack traces pointing at generated code. Can also be set via the `WORKFLOW_SOURCEMAP` environment variable. |
+
+### Returns
+
+Returns an array of Vite `Plugin` objects. Spread or pass the array directly to the `plugins` option of your Vite config — Vite flattens nested plugin arrays automatically.

package/docs/changelog/attributes-mvp.mdx

@@ -9,6 +9,18 @@ This is a minimal, **experimental** subset of the [planned Workflow Attributes f
 
 The MVP lets workflow code attach plaintext `string → string` metadata to a run, viewable in any observability surface that reads the `WorkflowRun` entity. It is deliberately narrow: write-only, no reads from inside a run, no list/filter endpoints, no event-log representation. The wire format and SDK surface are chosen so the full 5.0.0 implementation replaces this without source-level breaking changes for end users.
 
+## Native v4 follow-up
+
+The v4 implementation now completes the planned dispatch migration while preserving the experimental SDK name:
+
+- `experimental_setAttributes()` appends a native `attr_set` event from workflow and step bodies instead of mutating through the internal step bridge.
+- Native events carry writer attribution and are materialized immediately onto `run.attributes`.
+- `start(workflow, args, { attributes })` seeds attributes on the initial `run_created` event, including the resilient-start creation path.
+- The World spec is bumped to v4; attributes are supported for v4 runs rather than being backported into older run specifications.
+- The direct server attributes endpoint remains available only as a deprecated compatibility path for clients that shipped with the MVP.
+
+The remainder of this page documents the original MVP motivation and implementation.
+
 ## What MVP supports
 
 - `experimental_setAttributes(record)` callable from a **workflow body** (`"use workflow"` function), dispatched via an internal `__builtin_set_attributes` step bridge so the mutation gets a `step_created → step_completed` event pair
@@ -296,13 +308,13 @@ End-to-end in `workbench/nextjs-turbopack` (exercises the full SWC plugin + work
 - `Promise.all` of disjoint-key writes — every key persists
 - Workflow throws after an awaited `experimental_setAttributes` — the attribute persists on the now-`failed` run (the per-run file lock on `run_failed` re-reads inside the critical section so the attribute snapshot survives the lifecycle write)
 
-## Migration to 5.0.0
+## Migration to native v4
 
-When the full attributes feature ships:
+The native attributes follow-up applies this migration:
 
 - `experimental_setAttributes` (SDK) — unchanged signature, new dispatch path
 - `runs.experimentalSetAttributes` (world interface) — deprecated, then removed; replaced by `events.create(runId, { eventType: 'attr_set', eventData: { changes, writer } })`
-- Wire endpoint — `POST /v2/runs/:runId/attributes` removed; the same `changes` shape posts to `POST /v2/runs/:id/events`
+- Wire endpoint — `POST /v2/runs/:runId/attributes` is deprecated but temporarily retained for older clients; new calls post the same `changes` shape to events as `attr_set`
 - Pre-existing attribute values on MVP-era runs remain on the run entity but are not represented in the event log
 
 Skew protection means workflows started under the MVP will continue to run with the MVP dispatch path on their original deployment. New deployments use the new path. No in-place data migration is needed.

package/docs/changelog/eager-processing.mdx

@@ -157,15 +157,35 @@ To prevent deadlock when polling is executed inline by the step executor, `Run#p
 
 ### Mixed Suspensions
 
-A suspension may contain steps, hooks, and waits simultaneously. The handler creates events for all, then chooses between inline execution and queue dispatch:
+A suspension may contain steps, hooks, and waits simultaneously. The handler creates events for all, then dispatches everything we are not running inline as a single parallel batch of queue messages:
 
-- **Steps only** (no waits): one owned step is executed inline; the rest are queued. The loop continues after the inline step completes.
-- **Steps + at least one wait**: every step is queued (no inline execution). The handler returns with the wait timeout. Whichever lands first — a step's continuation or the wait timer — drives the next replay.
-- **Hooks / waits only**: handler returns with the wait timeout (or no timeout, for hook-only suspensions). The next continuation is driven by external resume or the wait timer.
+```
+ownedPendingSteps = pendingSteps.filter(owned by this handler)
+inlineStep        = ownedPendingSteps[0]   // optional
+
+dispatches = [
+  ...for each non-inline pendingStep: queue stepId message (idempotency=correlationId),
+  ...if soonest pending wait:          queue delayed continuation
+                                       (delaySeconds=min(remaining, maxDelay),
+                                        idempotency=waitCorrelationId[:hop|:secondBucket]),
+]
+await Promise.all(dispatches)
+
+if (!inlineStep) return
+await executeStep(inlineStep)
+```
+
+The wait timer is queued as its own continuation rather than encoded in the handler's return value (`{ timeoutSeconds }`). This is what makes `Promise.race(step, sleep)` behave correctly: even when the inline step blocks the handler for the full step duration, the wait continuation fires in a separate function invocation. If the sleep wins, that parallel invocation observes `wait_completed` via the "complete elapsed waits" pass and finishes the run; if the step wins, the wait continuation fires later and no-ops on the terminal run via the existing terminal-event check.
+
+Step queueing remains unconditional (covers crash recovery: if a prior handler wrote `step_created` but crashed before queueing, a later handler will queue it; idempotency keys dedupe redundant queues across concurrent handlers).
+
+Wait continuations are likewise deduplicated, keyed on the wait's correlation ID: while a wait is pending, every replay pass over the run re-observes it and would otherwise enqueue another delayed continuation. A key is attached in all cases, since some worlds serialize key-less workflow messages per run, which would park the continuation behind the handler's own inline step execution.
+
+Two situations deliver a continuation while its wait is still pending, and each varies the key so the re-enqueue isn't dropped by a world's dedupe window (which outlives the first delivery): waits longer than the maximum queue delay (23h, bounded by VQS's 24h message retention) are clamped and chained across hops, with the hop index suffixed to the key so each hop dedupes within its window but the chain always advances; and near-elapsed waits (≤2s remaining) use a second-bucketed key suffix so a continuation delivered marginally early (clock skew) can enqueue a fresh short-delay retry. See `runtime/wait-continuation.ts` for the full selection logic.
 
-The "no inline when there's a wait" carve-out is necessary to preserve `Promise.race(step, sleep)` semantics. Inline `await executeStep(...)` blocks the handler for the full step duration, and `wait_completed` events are only created on the *next* loop iteration's "complete elapsed waits" pass — so a longer-running step would always swallow the shorter sleep and `Promise.race` would resolve incorrectly. Queueing the step in this case lets the wait timer drive a continuation in parallel.
+The retry/throttle and hook-conflict paths still return `{ timeoutSeconds }` since their semantics are "redeliver THIS message after a delay" rather than "schedule a fresh wait timer." Those can be unified in a follow-up.
 
-Pure step suspensions (without waits) still benefit from inline execution; the carve-out only costs an extra queue roundtrip when a step and a sleep coexist.
+The unified dispatch requires `world-local` to honor `delaySeconds` on the queue (added in the same PR series). Without it, the wait continuation would fire instantly in dev and trigger a spurious replay before the wait elapsed (recoverable via redelivery, but inefficient and observable as duplicate `step_started` events under contention).
 
 ### VM Sandboxing
 

package/docs/errors/index.mdx

@@ -43,6 +43,9 @@ Fix common mistakes when creating and executing workflows in the **Workflow SDK*
     <Card href="/docs/errors/step-not-registered" title="step-not-registered">
         Resolve step not registered errors caused by deployment mismatches.
     </Card>
+    <Card href="/docs/errors/step-executed-multiple-times" title="Step executed multiple times">
+        Diagnose duplicate step_started events from function crashes, timeouts, or OOMs.
+    </Card>
     <Card href="/docs/errors/workflow-not-registered" title="workflow-not-registered">
         Resolve workflow not registered errors caused by deployment mismatches.
     </Card>

package/docs/errors/step-executed-multiple-times.mdx

@@ -0,0 +1,23 @@
+---
+title: Step executed multiple times
+description: A step ran more than once because its function invocation crashed before it could report a result.
+type: troubleshooting
+summary: Diagnose duplicate step_started events caused by function timeouts, OOMs, or network issues.
+prerequisites:
+  - /docs/foundations/workflows-and-steps
+related:
+  - /docs/observability
+  - /docs/foundations/errors-and-retries
+---
+
+There may be cases where you see multiple `step_started` events for the same step in a workflow run. This happens if the function invocation executing the step crashes unexpectedly, and the step can not report the error. The step will be re-tried according to your retry policy in this case, but no error will be visible in the [Observability UI](/docs/observability).
+
+## Common Causes
+
+- **Function timeouts**: if your step code runs longer than the configured maximum function duration, it will be killed. Compare the gap between the `step_started` events to your configured function duration to be sure.
+- **Out of memory (OOM)**: if your step code loads enough data into memory, especially if the step is invoked concurrently, the function invocation might run out of memory. You can see your function's peak memory use by going to the [Observability Query page](https://vercel.com/docs/observability) and showing the **Function Invocation Peak Memory** metric, then filtering down the **Route** to `/.well-known/workflow` endpoints.
+- **Network issues**: persistent firewall, network stability, and related issues might prevent your function from reporting results or errors. This should be temporary.
+
+## Getting Help
+
+If you consistently see multiple `step_started` events and have ruled out function timeouts, OOMs, and firewall issues, please [contact support](https://vercel.com/help).

package/docs/foundations/hooks.mdx

@@ -85,6 +85,35 @@ The key points:
 - You need the hook's `token` to resume it
 - The workflow will resume execution right where it left off
 
+### Checking for Token Conflicts
+
+Sometimes you need to know that a hook token has been claimed, but you do not want to wait for external data yet. Await `hook.getConflict()` for that:
+
+```typescript lineNumbers
+import { createHook } from "workflow";
+
+declare function processOrder(orderId: string): Promise<void>; // @setup
+
+export async function orderWorkflow(orderId: string) {
+  "use workflow";
+
+  using hook = createHook({
+    token: `order:${orderId}`
+  });
+
+  const conflict = await hook.getConflict(); // [!code highlight]
+  if (conflict) { // [!code highlight]
+    // Another active run already owns this token.
+    return { dedupedTo: conflict.runId };
+  }
+
+  // The hook token is registered and reserved here.
+  await processOrder(orderId);
+}
+```
+
+Calling `createHook()` on its own does not register the hook — registration is only committed when the workflow suspends. Awaiting `hook.getConflict()` suspends the workflow to commit the hook registration, then resolves with `null` once the hook is registered and ready to receive payloads, or with a `Run` handle for the run that owns the token if another active hook already claimed it (see [`HookConflictError`](/docs/errors/hook-conflict)). For `hook_conflict` events persisted by older worlds that did not record the owning run's ID, `getConflict()` rejects with `HookConflictError` instead of resolving with an incomplete handle. The conflicting run's accessors are durable steps, so the workflow can inspect `await conflict.status`, wait on `await conflict.returnValue`, or cancel the owner with `await conflict.cancel()` — see [Idempotency](/docs/foundations/idempotency) for these strategies.
+
 ### Custom Tokens for Deterministic Hooks
 
 By default, hooks generate a random token. However, you often want to use a **custom token** that external systems can reconstruct. This is especially useful for long-running workflows where the same workflow instance should handle multiple events.

package/docs/foundations/streaming.mdx

@@ -584,7 +584,7 @@ Stream errors don't trigger automatic retries for the producer step. Design your
 - [`sleep()` API Reference](/docs/api-reference/workflow/sleep) - Pause workflow execution for a duration
 - [`start()` API Reference](/docs/api-reference/workflow-api/start) - Start workflows and access the `Run` object
 - [`getRun()` API Reference](/docs/api-reference/workflow-api/get-run) - Retrieve runs and their streams later
-- [world.streams](/docs/api-reference/workflow-api/world/streams) - Low-level stream read/write/close via World SDK
+- [world.streams](/docs/api-reference/workflow-runtime/world/streams) - Low-level stream read/write/close via World SDK
 - [WorkflowAgent](https://ai-sdk.dev/v7/docs/agents/workflow-agent#workflowagent) - AI agents with durable, resumable streaming support
 - [Errors and Retries](/docs/foundations/errors-and-retries) - Understanding error handling and retry behavior
 - [Serialization](/docs/foundations/serialization) - Understanding what data types can be passed in workflows

package/docs/foundations/versioning.mdx

@@ -94,7 +94,7 @@ npx workflow cancel \
   --backend vercel
 ```
 
-The `--workflowName` filter expects the generated workflow ID, not only the exported function's short name. Use the `workflowName` value from `workflow inspect runs`, and use [`parseWorkflowName()`](/docs/api-reference/workflow-api/world/observability) when you need display-friendly names.
+The `--workflowName` filter expects the generated workflow ID, not only the exported function's short name. Use the `workflowName` value from `workflow inspect runs`, and use [`parseWorkflowName()`](/docs/api-reference/workflow-observability/parse-workflow-name) when you need display-friendly names.
 
 In the [observability UI](/docs/observability), use **Rerun on latest** to enqueue the workflow again with the same inputs against the latest deployment.
 

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

@@ -105,8 +105,8 @@ To add encryption support to a custom `World`:
 import type { WorkflowRun, World } from "@workflow/world";
 
 export const getEncryptionKeyForRun: World["getEncryptionKeyForRun"] = async (
-  run,
-  context
+  run: WorkflowRun | string,
+  context?: Record<string, unknown>
 ) => {
   const runId = typeof run === "string" ? run : run.runId;
   const deploymentId =

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

@@ -127,7 +127,7 @@ flowchart TD
 
 Unlike other entities, hooks don't have a `status` field—the states above are conceptual. An "active" hook is one that exists in storage, while "disposed" means the hook has been deleted. When a `hook_disposed` event is created, the hook record is removed rather than updated.
 
-While a hook is active, its token is reserved and cannot be used by other workflows. If a workflow attempts to create a hook with a token that is already in use by another active hook, a `hook_conflict` event is recorded instead of `hook_created`. Current worlds include the token and the run ID that currently owns it, though older persisted events or world implementations may only include the token. This causes the hook's promise to reject with a `HookConflictError`, which you can detect with `HookConflictError.is(error)`. See the [hook-conflict error](/docs/errors/hook-conflict) documentation for more details.
+While a hook is active, its token is reserved and cannot be used by other workflows. If a workflow attempts to create a hook with a token that is already in use by another active hook, a `hook_conflict` event is recorded instead of `hook_created`. Current worlds include the token and the run ID that currently owns it, though older persisted events or world implementations may only include the token. This causes `hook.getConflict()` to resolve with the conflicting run and the hook's payload promise to reject with a `HookConflictError`, which you can detect with `HookConflictError.is(error)`. See the [hook-conflict error](/docs/errors/hook-conflict) documentation for more details.
 
 When a hook is disposed (either explicitly or when its workflow completes), the token is released and can be claimed by future workflows. Hooks are automatically disposed when a workflow reaches a terminal state (`completed`, `failed`, or `cancelled`). The `hook_disposed` event is only needed for explicit disposal before workflow completion.
 
@@ -188,7 +188,7 @@ Events are categorized by the entity type they affect. Each event contains metad
 | Event | Description |
 |-------|-------------|
 | `hook_created` | Creates a new hook in `active` state. Contains the hook token and optional metadata. |
-| `hook_conflict` | Records that hook creation failed because the token is already in use by another active hook. Contains the token and, for current worlds, the active hook owner's run ID. The hook is not created, and awaiting the hook will reject with a `HookConflictError`. |
+| `hook_conflict` | Records that hook creation failed because the token is already in use by another active hook. Contains the token and, for current worlds, the active hook owner's run ID. The hook is not created: `hook.getConflict()` resolves with the conflicting run, and awaiting the hook payload rejects with a `HookConflictError`. |
 | `hook_received` | Records that a payload was delivered to the hook. The hook remains `active` and can receive more payloads. |
 | `hook_disposed` | Deletes the hook from storage (conceptually transitioning to `disposed` state). The token is released for reuse by future workflows. |
 

package/docs/observability/attributes.mdx

@@ -18,6 +18,15 @@ This feature is experimental and may change before the stable attributes API is
 [`experimental_setAttributes`](/docs/api-reference/workflow/experimental-set-attributes) attaches plaintext string metadata to the current workflow run. These attributes are displayed in observability CLI/UI.
 In the future, you'll be able to search and filter runs by attributes.
 
+You can also seed any attributes directly when starting a run:
+
+{/* @skip-typecheck: abbreviated usage; orderWorkflow is defined below */}
+```typescript lineNumbers
+const run = await start(orderWorkflow, ["ord_123"], {
+  attributes: { source: "checkout" }, // [!code highlight]
+})
+```
+
 ```typescript lineNumbers
 import { experimental_setAttributes } from "workflow"
 
@@ -57,10 +66,8 @@ Attribute keys must be 1-256 characters, values must be strings up to 256 bytes,
 
 While attributes are experimental:
 
-- Worlds that do not support attributes log a warning and ignore the call.
-- Workflow-body storage errors are logged after retries, but do not fail the workflow run.
+- Attributes require a World implementing spec version 4 or later.
+- Writes from workflow and step bodies append native `attr_set` events and immediately materialize `run.attributes`.
+- Storage errors surface rather than being silently ignored: transient errors on workflow-body writes are retried, and a write the World rejects as invalid (for example, exceeding the per-run attribute cap across multiple calls) fails the run with the validation error.
 - Step-body storage errors throw from `experimental_setAttributes` like any other step-side network write. Catch the error inside the step if the attribute is best-effort.
-- Setting attributes from a workflow body is currently slower than the final API will be, because each write goes through an internal workflow step. Step-body calls post directly to the World. Prefer batching related attributes in one call.
 - Reading and querying attributes is not available yet. A query API is planned.
-
-In a future release, using attributes with a World that does not support them, or when the World fails to store them, will fail with a [world error](/docs/api-reference/workflow-errors/workflow-world-error). This can be caught and handled to prevent failing a run.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "workflow",
-  "version": "5.0.0-beta.13",
+  "version": "5.0.0-beta.15",
   "description": "Workflow SDK - Build durable, resilient, and observable workflows",
   "main": "dist/typescript-plugin.cjs",
   "type": "module",
@@ -57,18 +57,18 @@
   },
   "dependencies": {
     "ms": "2.1.3",
-    "@workflow/astro": "5.0.0-beta.13",
-    "@workflow/cli": "5.0.0-beta.13",
-    "@workflow/core": "5.0.0-beta.13",
+    "@workflow/astro": "5.0.0-beta.15",
+    "@workflow/cli": "5.0.0-beta.15",
+    "@workflow/core": "5.0.0-beta.15",
     "@workflow/errors": "5.0.0-beta.7",
     "@workflow/typescript-plugin": "5.0.0-beta.4",
     "@workflow/utils": "5.0.0-beta.3",
-    "@workflow/next": "5.0.0-beta.13",
-    "@workflow/nest": "5.0.0-beta.13",
-    "@workflow/nitro": "5.0.0-beta.13",
-    "@workflow/nuxt": "5.0.0-beta.13",
-    "@workflow/sveltekit": "5.0.0-beta.13",
-    "@workflow/rollup": "5.0.0-beta.13"
+    "@workflow/next": "5.0.0-beta.15",
+    "@workflow/nest": "5.0.0-beta.15",
+    "@workflow/nitro": "5.0.0-beta.15",
+    "@workflow/nuxt": "5.0.0-beta.15",
+    "@workflow/sveltekit": "5.0.0-beta.15",
+    "@workflow/rollup": "5.0.0-beta.15"
   },
   "devDependencies": {
     "@types/ms": "2.1.0",

package/docs/api-reference/workflow-api/world/meta.json

@@ -1,4 +0,0 @@
-{
-  "title": "World SDK",
-  "pages": ["storage", "streams", "queue", "observability"]
-}

package/docs/api-reference/workflow-api/world/observability.mdx

@@ -1,164 +0,0 @@
----
-title: Observability Utilities
-description: Hydrate step I/O, parse display names, and decrypt workflow data using workflow/observability.
-type: reference
-summary: "Functions: hydrateResourceIO(), parseStepName(), parseWorkflowName(), parseClassName(), getEncryptionKeyForRun(), hydrateResourceIOWithKey()."
-prerequisites:
-  - /docs/api-reference/workflow-api/get-world
-related:
-  - /docs/api-reference/workflow-api/world/storage
-keywords:
-  - workflow/observability
-  - hydrateResourceIO
-  - observabilityRevivers
-  - parseStepName
-  - parseWorkflowName
-  - parseClassName
-  - getEncryptionKeyForRun
-  - hydrateResourceIOWithKey
-  - data hydration
-  - devalue deserialization
-  - encryption decryption
-  - display name parsing
----
-
-The `workflow/observability` module provides utilities for working with workflow data in observability and debugging tools. It includes functions to hydrate serialized step I/O, parse machine-readable names into display-friendly formats, and decrypt encrypted workflow data.
-
-## Import
-
-```typescript lineNumbers
-import { // [!code highlight]
-  hydrateResourceIO, // [!code highlight]
-  observabilityRevivers, // [!code highlight]
-  parseStepName, // [!code highlight]
-  parseWorkflowName, // [!code highlight]
-  parseClassName, // [!code highlight]
-} from "workflow/observability"; // [!code highlight]
-```
-
-## Data Hydration
-
-### hydrateResourceIO()
-
-Deserialize step or run data that was serialized using the [devalue](https://github.com/Rich-Harris/devalue) format. Required to display step input/output in your UI.
-
-```typescript lineNumbers
-import { hydrateResourceIO, observabilityRevivers } from "workflow/observability"; // [!code highlight]
-
-const step = await world.steps.get(runId, stepId);
-const hydrated = hydrateResourceIO(step, observabilityRevivers); // [!code highlight]
-console.log(hydrated.input, hydrated.output);
-```
-
-**Parameters:**
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `resource` | `Step \| WorkflowRun` | The step or run with serialized data |
-| `revivers` | `Revivers` | Reviver functions for deserialization. Use `observabilityRevivers` for standard use. |
-
-**Returns:** The resource with hydrated `input` and `output` fields.
-
-### observabilityRevivers
-
-A set of reviver functions that handle standard workflow serialization types (Date, Map, Set, Error, etc.).
-
-## Name Parsing
-
-Workflow and step names are stored as machine-readable identifiers. These utilities extract display-friendly names. All return `{ shortName: string, moduleSpecifier: string } | null`.
-
-### parseStepName()
-
-```typescript lineNumbers
-import { parseStepName } from "workflow/observability"; // [!code highlight]
-
-const parsed = parseStepName("step//./src/workflows/order//processPayment"); // [!code highlight]
-// parsed?.shortName → "processPayment"
-// parsed?.moduleSpecifier → "./src/workflows/order"
-```
-
-### parseWorkflowName()
-
-```typescript lineNumbers
-import { parseWorkflowName } from "workflow/observability"; // [!code highlight]
-
-const parsed = parseWorkflowName("workflow//./src/workflows/order//processOrder"); // [!code highlight]
-// parsed?.shortName → "processOrder"
-```
-
-### parseClassName()
-
-```typescript lineNumbers
-import { parseClassName } from "workflow/observability"; // [!code highlight]
-
-const parsed = parseClassName("class//./src/models//User"); // [!code highlight]
-// parsed?.shortName → "User"
-```
-
-## Encryption
-
-For workflows with encrypted step data, decrypt before hydrating.
-
-### getEncryptionKeyForRun()
-
-Retrieve the encryption key used for a specific workflow run.
-
-{/* @expect-error:2305 */}
-```typescript lineNumbers
-import { getEncryptionKeyForRun } from "workflow/observability"; // [!code highlight]
-
-const key = await getEncryptionKeyForRun(runId); // [!code highlight]
-```
-
-**Parameters:**
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `runId` | `string` | The workflow run ID |
-
-**Returns:** Encryption key for the run
-
-### hydrateResourceIOWithKey()
-
-Hydrate step or run data using a decryption key. Use this instead of `hydrateResourceIO()` when data is encrypted.
-
-{/* @expect-error:2305,2724 */}
-```typescript lineNumbers
-import { getEncryptionKeyForRun, hydrateResourceIOWithKey } from "workflow/observability"; // [!code highlight]
-
-const key = await getEncryptionKeyForRun(runId); // [!code highlight]
-const hydrated = hydrateResourceIOWithKey(step, key); // [!code highlight]
-```
-
-**Parameters:**
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `resource` | `Step \| WorkflowRun` | The step or run with encrypted serialized data |
-| `key` | `EncryptionKey` | The encryption key from `getEncryptionKeyForRun()` |
-
-**Returns:** The resource with decrypted and hydrated `input` and `output` fields.
-
-## Examples
-
-### Parse Display Names for a Run's Steps
-
-```typescript lineNumbers
-import { getWorld } from "workflow/runtime";
-import { parseStepName, parseWorkflowName } from "workflow/observability"; // [!code highlight]
-
-const world = await getWorld();
-const run = await world.runs.get(runId, { resolveData: "none" });
-console.log("Workflow:", parseWorkflowName(run.workflowName)?.shortName); // [!code highlight]
-
-const steps = await world.steps.list({ runId, resolveData: "none" });
-for (const step of steps.data) {
-  const parsed = parseStepName(step.stepName); // [!code highlight]
-  console.log(`  ${parsed?.shortName}: ${step.status}`); // [!code highlight]
-}
-```
-
-## Related
-
-- [Storage](/docs/api-reference/workflow-api/world/storage) — Query runs, steps, hooks, and events
-- [Serialization](/docs/foundations/serialization) — How workflow data is serialized