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

package/docs/api-reference/workflow-nest/index.mdx

@@ -0,0 +1,31 @@
+---
+title: "workflow/nest"
+description: NestJS integration for workflow bundling and HTTP routing.
+type: overview
+summary: Explore the NestJS integration for workflow bundle building and runtime routing.
+related:
+  - /docs/getting-started/nestjs
+---
+
+NestJS integration for Workflow SDK. The `WorkflowModule` builds the workflow bundles on application startup and registers the controller that serves the workflow runtime routes.
+
+<Callout>
+NestJS integration is experimental and not yet supported for deployment to Vercel. The same exports are also available from the `@workflow/nest` package.
+</Callout>
+
+## Exports
+
+<Cards>
+    <Card title="WorkflowModule" href="/docs/api-reference/workflow-nest/workflow-module">
+        NestJS module that builds workflow bundles on startup and registers the workflow controller
+    </Card>
+    <Card title="NestLocalBuilder" href="/docs/api-reference/workflow-nest/nest-local-builder">
+        Builder that compiles workflow files into step, workflow, and webhook bundles
+    </Card>
+    <Card title="WorkflowController" href="/docs/api-reference/workflow-nest/workflow-controller">
+        Controller that serves the workflow runtime routes under `.well-known/workflow/v1`
+    </Card>
+    <Card title="configureWorkflowController()" href="/docs/api-reference/workflow-nest/configure-workflow-controller">
+        Points `WorkflowController` at the directory containing the generated workflow bundles
+    </Card>
+</Cards>

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

@@ -0,0 +1,9 @@
+{
+  "title": "workflow/nest",
+  "pages": [
+    "workflow-module",
+    "nest-local-builder",
+    "workflow-controller",
+    "configure-workflow-controller"
+  ]
+}

package/docs/api-reference/workflow-nest/nest-local-builder.mdx

@@ -0,0 +1,64 @@
+---
+title: NestLocalBuilder
+description: Builder that compiles workflow files into bundles for NestJS apps.
+type: reference
+summary: Use NestLocalBuilder to build workflow bundles programmatically in a NestJS project.
+prerequisites:
+  - /docs/getting-started/nestjs
+---
+
+Builder that scans a NestJS project for workflow files and compiles them into the step, workflow, and webhook bundles plus a manifest. [`WorkflowModule.forRoot()`](/docs/api-reference/workflow-nest/workflow-module) creates and runs one automatically on startup — instantiate it yourself only when you need to build bundles outside the module lifecycle (e.g. a custom build script for production with `skipBuild`).
+
+## Usage
+
+```typescript title="scripts/build-workflows.ts" lineNumbers
+import { NestLocalBuilder } from "workflow/nest"; // [!code highlight]
+
+const builder = new NestLocalBuilder({
+  dirs: ["src"],
+});
+
+await builder.build(); // [!code highlight]
+
+console.log(`Workflow bundles written to ${builder.outDir}`);
+```
+
+## API Signature
+
+### Constructor
+
+`new NestLocalBuilder(options?)` creates a builder for the given options.
+
+### Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `options` | `NestBuilderOptions` | Optional. Configures the workflow build. |
+
+#### NestBuilderOptions
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `workingDir` | `string` | `process.cwd()` | Working directory for the NestJS application. |
+| `dirs` | `string[]` | `['src']` | Directories to scan for workflow files. |
+| `outDir` | `string` | `'.nestjs/workflow'` (relative to `workingDir`) | Output directory for generated workflow bundles. |
+| `watch` | `boolean` | `false` | Enable watch mode for development. |
+| `moduleType` | `'es6' \| 'commonjs'` | `'es6'` | SWC module compilation type. When `'commonjs'`, the builder rewrites externalized imports in the steps bundle to use `require()` via `createRequire`, avoiding ESM/CJS named-export interop issues with SWC's output. |
+| `distDir` | `string` | `'dist'` | Directory where NestJS compiles `.ts` source files to `.js` (relative to `workingDir`). Used when `moduleType` is `'commonjs'` to resolve compiled file paths. Should match the `outDir` in your `tsconfig.json`. |
+| `sourcemap` | `boolean \| 'inline' \| 'linked' \| 'external' \| 'both'` | `'inline'` | Controls source maps on generated workflow bundles. Accepts the same values as esbuild's `sourcemap` option. Can also be set via the `WORKFLOW_SOURCEMAP` environment variable. |
+
+### Methods
+
+#### `build()`
+
+Builds the workflow bundles. Writes `steps.mjs`, `workflows.mjs`, `webhook.mjs`, and `manifest.json` to the output directory (plus a `.gitignore` covering the generated files when not deploying to Vercel). Returns `Promise<void>`.
+
+### Properties
+
+#### `outDir`
+
+Read-only getter that returns the output directory for generated workflow bundles — the `outDir` option as passed, or the default `.nestjs/workflow` resolved against `workingDir`.
+
+### Returns
+
+The constructor returns a `NestLocalBuilder` instance.

package/docs/api-reference/workflow-nest/workflow-controller.mdx

@@ -0,0 +1,40 @@
+---
+title: WorkflowController
+description: NestJS controller that serves the workflow runtime routes.
+type: reference
+summary: WorkflowController handles the well-known workflow endpoints in a NestJS app.
+prerequisites:
+  - /docs/getting-started/nestjs
+---
+
+NestJS controller that handles the well-known workflow endpoints under `.well-known/workflow/v1`. It dynamically imports the generated workflow bundles and converts between Express/Fastify requests and the Web API `Request`/`Response` objects the workflow runtime expects. Both the Express and Fastify HTTP adapters are supported.
+
+[`WorkflowModule.forRoot()`](/docs/api-reference/workflow-nest/workflow-module) registers this controller automatically — you only register it yourself if you are not using `WorkflowModule`.
+
+## Usage
+
+When registering the controller manually, call [`configureWorkflowController`](/docs/api-reference/workflow-nest/configure-workflow-controller) first so it can locate the generated bundles; its route handlers throw otherwise.
+
+```typescript title="src/app.module.ts" lineNumbers
+import { join } from "node:path";
+import { Module } from "@nestjs/common";
+import {
+  configureWorkflowController, // [!code highlight]
+  WorkflowController, // [!code highlight]
+} from "workflow/nest";
+
+configureWorkflowController(join(process.cwd(), ".nestjs/workflow")); // [!code highlight]
+
+@Module({
+  controllers: [WorkflowController], // [!code highlight]
+})
+export class AppModule {}
+```
+
+## Routes
+
+| Route | Method | Description |
+| --- | --- | --- |
+| `/.well-known/workflow/v1/flow` | `POST` | Executes workflow and step work items via the combined handler in `workflows.mjs` (step registrations are imported from `steps.mjs` first). |
+| `/.well-known/workflow/v1/webhook/:token` | Any | Forwards webhook requests to the handler in `webhook.mjs`. |
+| `/.well-known/workflow/v1/manifest.json` | `GET` | Serves the workflow manifest. Responds with `404` unless the `WORKFLOW_PUBLIC_MANIFEST=1` environment variable is set. |

package/docs/api-reference/workflow-nest/workflow-module.mdx

@@ -0,0 +1,74 @@
+---
+title: WorkflowModule
+description: NestJS module that builds workflow bundles and registers the workflow controller.
+type: reference
+summary: Import WorkflowModule.forRoot() in your AppModule to enable workflows in a NestJS app.
+prerequisites:
+  - /docs/getting-started/nestjs
+---
+
+NestJS module that provides workflow functionality. It builds the workflow bundles on module initialization (`onModuleInit`) and registers the [`WorkflowController`](/docs/api-reference/workflow-nest/workflow-controller) that serves the workflow runtime routes.
+
+## Usage
+
+Add `WorkflowModule.forRoot()` to the `imports` array of your root module.
+
+```typescript title="src/app.module.ts" lineNumbers
+import { Module } from "@nestjs/common";
+import { WorkflowModule } from "workflow/nest"; // [!code highlight]
+
+@Module({
+  imports: [WorkflowModule.forRoot()], // [!code highlight]
+})
+export class AppModule {}
+```
+
+If your NestJS project compiles to CommonJS via SWC, pass `moduleType` and `distDir` so the builder can rewrite imports in the generated bundles:
+
+```typescript title="src/app.module.ts" lineNumbers
+import { Module } from "@nestjs/common";
+import { WorkflowModule } from "workflow/nest";
+
+@Module({
+  imports: [
+    WorkflowModule.forRoot({
+      moduleType: "commonjs", // [!code highlight]
+      distDir: "dist", // [!code highlight]
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+## API Signature
+
+### Static Methods
+
+#### `forRoot(options?)`
+
+Configures the module and returns a NestJS `DynamicModule` registered as `global`. It calls [`configureWorkflowController`](/docs/api-reference/workflow-nest/configure-workflow-controller) with the resolved output directory, and (unless `skipBuild` is set) creates a [`NestLocalBuilder`](/docs/api-reference/workflow-nest/nest-local-builder) that builds the workflow bundles when the module initializes.
+
+### Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `options` | `WorkflowModuleOptions` | Optional. Configures the workflow build. |
+
+#### WorkflowModuleOptions
+
+Extends [`NestBuilderOptions`](/docs/api-reference/workflow-nest/nest-local-builder#nestbuilderoptions) — all builder options are accepted, plus `skipBuild`:
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `skipBuild` | `boolean` | `false` | Skip building workflow bundles on startup. Useful in production when the bundles are pre-built. |
+| `workingDir` | `string` | `process.cwd()` | Working directory for the NestJS application. |
+| `dirs` | `string[]` | `['src']` | Directories to scan for workflow files. |
+| `outDir` | `string` | `'.nestjs/workflow'` (relative to `workingDir`) | Output directory for generated workflow bundles. |
+| `watch` | `boolean` | `false` | Enable watch mode for development. |
+| `moduleType` | `'es6' \| 'commonjs'` | `'es6'` | SWC module compilation type. Set to `'commonjs'` if your NestJS project compiles to CJS via SWC. |
+| `distDir` | `string` | `'dist'` | Directory where NestJS compiles `.ts` source files to `.js` (relative to `workingDir`). Used when `moduleType` is `'commonjs'`. Should match the `outDir` in your `tsconfig.json`. |
+| `sourcemap` | `boolean \| 'inline' \| 'linked' \| 'external' \| 'both'` | `'inline'` | Controls source maps on generated workflow bundles. Can also be set via the `WORKFLOW_SOURCEMAP` environment variable. |
+
+### Returns
+
+`forRoot()` returns a `DynamicModule` to include in the `imports` array of your root module.

package/docs/api-reference/workflow-nitro/index.mdx

@@ -0,0 +1,59 @@
+---
+title: "workflow/nitro"
+description: Nitro module for automatic workflow bundling and route registration.
+type: overview
+summary: Explore the Nitro module that enables workflow directive transformation in Nitro apps.
+related:
+  - /docs/getting-started/nitro
+---
+
+Nitro integration for Workflow SDK. The `workflow/nitro` entry point's default export is a [Nitro module](https://v3.nitro.build/guide/modules) — it has no callable API. You enable it by adding it to the `modules` array of your Nitro config and configure it via the `workflow` key.
+
+## Usage
+
+```typescript title="nitro.config.ts" lineNumbers
+import { defineConfig } from "nitro";
+
+export default defineConfig({
+  serverDir: "./server",
+  modules: ["workflow/nitro"], // [!code highlight]
+});
+```
+
+When enabled, the module:
+
+- Transforms `"use workflow"` and `"use step"` directives during bundling.
+- Builds the workflow, step, and webhook bundles, and rebuilds them on file changes in development.
+- Registers the workflow runtime routes under `/.well-known/workflow/v1/`.
+- Serves a redirect to the local observability dashboard at `/_workflow` in development.
+- Configures Vercel function rules (queue triggers and `maxDuration`) for the workflow routes when deploying to Vercel.
+
+## Module Options
+
+Options are read from the `workflow` key of your Nitro config. The option type is exported as `ModuleOptions`:
+
+```typescript title="nitro.config.ts" lineNumbers
+import { defineConfig } from "nitro";
+import type { ModuleOptions } from "workflow/nitro"; // [!code highlight]
+
+const workflow: ModuleOptions = {
+  runtime: "nodejs22.x",
+  sourcemap: "inline",
+};
+
+export default defineConfig({
+  modules: ["workflow/nitro"],
+  workflow, // [!code highlight]
+});
+```
+
+| 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. |
+
+## Vite-based Nitro
+
+If you use Nitro through its Vite plugin (`nitro/vite`) instead of a standalone `nitro.config.ts`, use the [`workflow/vite`](/docs/api-reference/workflow-vite) entry point, which wraps this module as a Vite plugin and accepts the same `ModuleOptions`.

package/docs/api-reference/workflow-nuxt/index.mdx

@@ -0,0 +1,47 @@
+---
+title: "workflow/nuxt"
+description: Nuxt module for automatic workflow bundling and runtime configuration.
+type: overview
+summary: Explore the Nuxt module that enables workflow directive transformation in Nuxt apps.
+related:
+  - /docs/getting-started/nuxt
+---
+
+Nuxt integration for Workflow SDK. The `workflow/nuxt` entry point's default export is a Nuxt module — it has no callable API. You enable it by adding it to the `modules` array of your Nuxt config and configure it via the `workflow` key.
+
+## Usage
+
+```typescript title="nuxt.config.ts" lineNumbers
+import { defineNuxtConfig } from "nuxt/config";
+
+export default defineNuxtConfig({
+  modules: ["workflow/nuxt"], // [!code highlight]
+  compatibilityDate: "latest",
+});
+```
+
+When enabled, the module:
+
+- Registers the [`workflow/nitro`](/docs/api-reference/workflow-nitro) module on Nuxt's Nitro server, which transforms `"use workflow"` and `"use step"` directives, builds the workflow bundles, and registers the workflow runtime routes under `/.well-known/workflow/v1/`.
+- Configures Vite to bundle (rather than externalize) the Workflow SDK packages in SSR mode so workflow code is transformed correctly.
+- Enables the `workflow` TypeScript plugin by default for IDE IntelliSense.
+
+## Module Options
+
+Options are read from the `workflow` key of your Nuxt config. The option type is exported as `ModuleOptions`:
+
+```typescript title="nuxt.config.ts" lineNumbers
+import { defineNuxtConfig } from "nuxt/config";
+
+export default defineNuxtConfig({
+  modules: ["workflow/nuxt"],
+  workflow: {
+    typescriptPlugin: false, // [!code highlight]
+  },
+  compatibilityDate: "latest",
+});
+```
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `typescriptPlugin` | `boolean` | `true` | Adds the `workflow` TypeScript plugin to the generated `tsconfig.json` for IDE IntelliSense. Set to `false` to disable it. |

package/docs/api-reference/workflow-observability/hydrate-data.mdx

@@ -0,0 +1,35 @@
+---
+title: hydrateData
+description: Hydrate a single serialized value from workflow storage into a plain JavaScript value.
+type: reference
+summary: Use hydrateData to deserialize a single value when hydrateResourceIO's field mapping doesn't apply.
+related:
+  - /docs/api-reference/workflow-observability/hydrate-resource-io
+  - /docs/api-reference/workflow-observability/observability-revivers
+---
+
+Hydrates (deserializes) a single value that was stored by the workflow runtime. This is the lower-level building block behind [`hydrateResourceIO()`](/docs/api-reference/workflow-observability/hydrate-resource-io) — use it when you have a raw serialized value rather than a whole resource, such as a single field from an event payload.
+
+```typescript lineNumbers
+import { hydrateData, observabilityRevivers } from "workflow/observability"; // [!code highlight]
+declare const serialized: unknown; // @setup
+
+const value = hydrateData(serialized, observabilityRevivers); // [!code highlight]
+```
+
+## API Signature
+
+### Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `value` | `unknown` | The serialized value from workflow storage |
+| `revivers` | `Revivers` | Reviver functions for deserialization. Use [`observabilityRevivers`](/docs/api-reference/workflow-observability/observability-revivers) for standard use. |
+
+### Returns
+
+The hydrated plain JavaScript value. The input is handled by shape:
+
+- Format-prefixed binary data (`Uint8Array`) is decoded and parsed from the [devalue](https://github.com/Rich-Harris/devalue) format
+- Encrypted data is returned as-is (a raw `Uint8Array`) — see [Encrypted Data](/docs/api-reference/workflow-observability#encrypted-data)
+- Already-plain values (numbers, strings, `null`) are returned unchanged

package/docs/api-reference/workflow-observability/hydrate-resource-io.mdx

@@ -0,0 +1,62 @@
+---
+title: hydrateResourceIO
+description: Hydrate the serialized data fields of a run, step, hook, or event for display.
+type: reference
+summary: Use hydrateResourceIO with observabilityRevivers to deserialize step input/output for display in observability tools.
+prerequisites:
+  - /docs/api-reference/workflow-runtime/get-world
+related:
+  - /docs/api-reference/workflow-observability/observability-revivers
+  - /docs/api-reference/workflow-runtime/world/storage
+---
+
+Hydrates (deserializes) the data fields of a resource returned by the [World SDK](/docs/api-reference/workflow-runtime/world) — a workflow run, step, hook, or event. Workflow data is serialized using the [devalue](https://github.com/Rich-Harris/devalue) format, so this is required before displaying step input/output in a UI.
+
+The function dispatches on the resource shape: steps get `input`/`output` hydrated, hooks get `metadata`, events get `eventData`, and runs get `input`/`output`.
+
+```typescript lineNumbers
+import { getWorld } from "workflow/runtime";
+import { hydrateResourceIO, observabilityRevivers } from "workflow/observability"; // [!code highlight]
+declare const runId: string; // @setup
+declare const stepId: string; // @setup
+
+const world = await getWorld();
+const step = await world.steps.get(runId, stepId);
+const hydrated = hydrateResourceIO(step, observabilityRevivers); // [!code highlight]
+console.log(hydrated.input, hydrated.output);
+```
+
+## API Signature
+
+### Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `resource` | `WorkflowRun \| Step \| Hook \| Event` | The resource with serialized data fields |
+| `revivers` | `Revivers` | Reviver functions for deserialization. Use [`observabilityRevivers`](/docs/api-reference/workflow-observability/observability-revivers) for standard use. |
+
+### Returns
+
+The same resource with its data fields hydrated into plain JavaScript values.
+
+<Callout type="info">
+  Encrypted data fields pass through as raw `Uint8Array` values rather than being decrypted — see [Encrypted Data](/docs/api-reference/workflow-observability#encrypted-data).
+</Callout>
+
+## Examples
+
+### Display a Run's Steps with Hydrated I/O
+
+```typescript lineNumbers
+import { getWorld } from "workflow/runtime";
+import { hydrateResourceIO, observabilityRevivers } from "workflow/observability"; // [!code highlight]
+declare const runId: string; // @setup
+
+const world = await getWorld();
+const steps = await world.steps.list({ runId, resolveData: "all" });
+
+for (const step of steps.data) {
+  const hydrated = hydrateResourceIO(step, observabilityRevivers); // [!code highlight]
+  console.log(step.stepName, hydrated.input, hydrated.output);
+}
+```

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

@@ -0,0 +1,64 @@
+---
+title: "workflow/observability"
+description: Utilities to hydrate serialized step I/O and parse machine-readable workflow names for display.
+type: overview
+summary: Explore utilities for hydrating serialized workflow data and parsing display names in observability tools.
+keywords:
+  - workflow/observability
+  - hydrateResourceIO
+  - observabilityRevivers
+  - hydrateData
+  - parseStepName
+  - parseWorkflowName
+  - parseClassName
+  - data hydration
+  - devalue deserialization
+  - display name parsing
+---
+
+API reference for observability utilities from the `workflow/observability` package.
+
+The observability package provides utilities for working with workflow data in observability and debugging tools — hydrating serialized step I/O for display, and parsing machine-readable names into display-friendly formats.
+
+```typescript lineNumbers
+import { // [!code highlight]
+  hydrateResourceIO, // [!code highlight]
+  observabilityRevivers, // [!code highlight]
+  hydrateData, // [!code highlight]
+  parseStepName, // [!code highlight]
+  parseWorkflowName, // [!code highlight]
+  parseClassName, // [!code highlight]
+} from "workflow/observability"; // [!code highlight]
+```
+
+## Data Hydration
+
+<Cards>
+    <Card href="/docs/api-reference/workflow-observability/hydrate-resource-io" title="hydrateResourceIO()">
+        Hydrate the serialized data fields of a run, step, hook, or event for display.
+    </Card>
+    <Card href="/docs/api-reference/workflow-observability/observability-revivers" title="observabilityRevivers">
+        Standard revivers for deserializing workflow data types (Date, Map, Set, streams, etc.).
+    </Card>
+    <Card href="/docs/api-reference/workflow-observability/hydrate-data" title="hydrateData()">
+        Hydrate a single serialized value (lower-level than hydrateResourceIO).
+    </Card>
+</Cards>
+
+## Name Parsing
+
+<Cards>
+    <Card href="/docs/api-reference/workflow-observability/parse-step-name" title="parseStepName()">
+        Parse a machine-readable step name into display-friendly components.
+    </Card>
+    <Card href="/docs/api-reference/workflow-observability/parse-workflow-name" title="parseWorkflowName()">
+        Parse a machine-readable workflow name into display-friendly components.
+    </Card>
+    <Card href="/docs/api-reference/workflow-observability/parse-class-name" title="parseClassName()">
+        Parse a machine-readable class ID into display-friendly components.
+    </Card>
+</Cards>
+
+## Encrypted Data
+
+When a [World](/docs/api-reference/workflow-runtime/world) stores encrypted data, the hydration utilities intentionally leave encrypted values untouched: [`hydrateData()`](/docs/api-reference/workflow-observability/hydrate-data) and [`hydrateResourceIO()`](/docs/api-reference/workflow-observability/hydrate-resource-io) return encrypted fields as raw `Uint8Array` values so observability tools can detect them and decide how to render them (for example, the Workflow CLI shows an "Encrypted" placeholder). Decryption is handled by the runtime and the World implementation — see [Encryption](/docs/how-it-works/encryption) for how keys are managed.

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

@@ -0,0 +1,11 @@
+{
+  "title": "workflow/observability",
+  "pages": [
+    "hydrate-resource-io",
+    "observability-revivers",
+    "hydrate-data",
+    "parse-step-name",
+    "parse-workflow-name",
+    "parse-class-name"
+  ]
+}

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

@@ -0,0 +1,50 @@
+---
+title: observabilityRevivers
+description: Standard reviver functions for deserializing workflow data types in observability tools.
+type: reference
+summary: Pass observabilityRevivers to hydrateResourceIO or hydrateData to deserialize standard workflow data types.
+related:
+  - /docs/api-reference/workflow-observability/hydrate-resource-io
+  - /docs/api-reference/workflow-observability/hydrate-data
+---
+
+A set of reviver functions that handle the workflow serialization format's workflow-specific types — streams, step/workflow function references, class instances, `AbortController`/`AbortSignal`, and `DOMException` — reviving them as display-friendly marker objects or strings. Built-in JavaScript types (`Date`, `Map`, `Set`, `RegExp`, etc.) are handled by the devalue format itself and need no revivers.
+
+Pass it as the `revivers` argument to [`hydrateResourceIO()`](/docs/api-reference/workflow-observability/hydrate-resource-io) or [`hydrateData()`](/docs/api-reference/workflow-observability/hydrate-data).
+
+```typescript lineNumbers
+import { hydrateResourceIO, observabilityRevivers } from "workflow/observability"; // [!code highlight]
+import type { Step } from "@workflow/world";
+declare const step: Step; // @setup
+
+const hydrated = hydrateResourceIO(step, observabilityRevivers); // [!code highlight]
+```
+
+## API Signature
+
+```typescript
+import type { Revivers } from "workflow/observability";
+
+declare const observabilityRevivers: Revivers;
+```
+
+Where `Revivers` is:
+
+```typescript
+type Revivers = Record<string, (value: any) => any>;
+```
+
+Each key is a serialized type tag, and each function revives a serialized value of that type. You can spread `observabilityRevivers` into a custom reviver map to override how specific types are displayed:
+
+```typescript lineNumbers
+import { hydrateData, observabilityRevivers } from "workflow/observability";
+declare const value: unknown; // @setup
+
+const customRevivers = {
+  ...observabilityRevivers,
+  // Render stream references as plain strings instead of marker objects
+  ReadableStream: () => "<stream>",
+};
+
+const hydrated = hydrateData(value, customRevivers);
+```

package/docs/api-reference/workflow-observability/parse-class-name.mdx

@@ -0,0 +1,41 @@
+---
+title: parseClassName
+description: Parse a machine-readable class ID into display-friendly components.
+type: reference
+summary: Use parseClassName to extract a display-friendly class name from a serialized class instance identifier.
+related:
+  - /docs/api-reference/workflow-observability/parse-step-name
+  - /docs/api-reference/workflow-observability/parse-workflow-name
+  - /docs/api-reference/workflow-serde
+---
+
+Serialized class instances reference their class with machine-readable IDs like `class//./src/models//User`. This function parses them into components suitable for display in a UI.
+
+```typescript lineNumbers
+import { parseClassName } from "workflow/observability"; // [!code highlight]
+
+const parsed = parseClassName("class//./src/models//User"); // [!code highlight]
+// parsed?.shortName → "User"
+// parsed?.moduleSpecifier → "./src/models"
+// parsed?.functionName → "User"
+```
+
+## API Signature
+
+### Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `name` | `string` | The machine-readable class ID |
+
+### Returns
+
+`{ shortName: string; moduleSpecifier: string; functionName: string } | null`
+
+| Property | Description |
+|----------|-------------|
+| `shortName` | The display name of the class (e.g. `"User"`). |
+| `moduleSpecifier` | The module the class is defined in — a relative path (`./src/models`) or a package specifier (`point@0.0.1`). |
+| `functionName` | The class name as recorded by the compiler. |
+
+Returns `null` when the input is not a valid class ID.

package/docs/api-reference/workflow-observability/parse-step-name.mdx

@@ -0,0 +1,40 @@
+---
+title: parseStepName
+description: Parse a machine-readable step name into display-friendly components.
+type: reference
+summary: Use parseStepName to extract a display-friendly short name from a step's machine-readable identifier.
+related:
+  - /docs/api-reference/workflow-observability/parse-workflow-name
+  - /docs/api-reference/workflow-observability/parse-class-name
+---
+
+Step names are stored as machine-readable identifiers like `step//./src/workflows/order//processPayment`. This function parses them into components suitable for display in a UI.
+
+```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"
+// parsed?.functionName → "processPayment"
+```
+
+## API Signature
+
+### Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `name` | `string` | The machine-readable step name (e.g. from `step.stepName`) |
+
+### Returns
+
+`{ shortName: string; moduleSpecifier: string; functionName: string } | null`
+
+| Property | Description |
+|----------|-------------|
+| `shortName` | The display name — the last segment of the function name. For nested steps like `processOrder/chargeCard`, this is `"chargeCard"`. |
+| `moduleSpecifier` | The module the step is defined in — a relative path (`./src/workflows/order`) or a package specifier (`@myorg/tasks@2.0.0`). |
+| `functionName` | The full function name including nesting (e.g. `processOrder/chargeCard`). |
+
+Returns `null` when the input is not a valid step name.