workflow 5.0.0-beta.0 → 5.0.0-beta.2

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

@@ -2,26 +2,26 @@
 title: Streams
 description: Read, write, and manage real-time data streams for workflow runs.
 type: reference
-summary: "Methods: writeToStream(), writeToStreamMulti(), readFromStream(), closeStream(), listStreamsByRunId(), getStreamChunks(), getStreamInfo(). Stream methods live directly on the world object."
+summary: "Methods: streams.write(), streams.writeMulti(), streams.get(), streams.close(), streams.list(), streams.getChunks(), streams.getInfo(). Stream methods live on world.streams."
 prerequisites:
   - /docs/api-reference/workflow-api/get-world
 related:
   - /docs/foundations/streaming
   - /docs/api-reference/workflow/get-writable
 keywords:
-  - writeToStream
-  - writeToStreamMulti
-  - readFromStream
-  - closeStream
-  - listStreamsByRunId
-  - getStreamChunks
-  - getStreamInfo
+  - streams.write
+  - streams.writeMulti
+  - streams.get
+  - streams.close
+  - streams.list
+  - streams.getChunks
+  - streams.getInfo
   - Streamer interface
   - real-time streaming
   - stream lifecycle
 ---
 
-Stream methods live directly on the `world` object returned by `getWorld()`. Use them to write chunks, read streams, and manage stream lifecycle outside of the standard `getWritable()` pattern.
+Stream methods live on `world.streams` (the `streams` sub-object of the `World` instance returned by `await getWorld()`). Use them to write chunks, read streams, and manage stream lifecycle outside of the standard `getWritable()` pattern.
 
 <Callout type="info">
   For most streaming use cases, use [`getWritable()`](/docs/api-reference/workflow/get-writable) inside steps. Direct stream methods are for advanced scenarios like building custom stream consumers or managing streams from outside a workflow.
@@ -32,82 +32,83 @@ Stream methods live directly on the `world` object returned by `getWorld()`. Use
 ```typescript lineNumbers
 import { getWorld } from "workflow/runtime";
 
-const world = getWorld(); // [!code highlight]
-// Stream methods are called directly on world — e.g. world.writeToStream()
+const world = await getWorld(); // [!code highlight]
+// Stream methods are called on world.streams — e.g. world.streams.write()
 ```
 
 ## Methods
 
-### writeToStream()
+### write()
 
 Write a data chunk to a named stream.
 
 ```typescript lineNumbers
-await world.writeToStream("default", runId, chunk); // [!code highlight]
+await world.streams.write(runId, "default", chunk); // [!code highlight]
 ```
 
 **Parameters:**
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `name` | `string` | The stream name |
 | `runId` | `string` | The workflow run ID |
+| `name` | `string` | The stream name |
 | `chunk` | `string \| Uint8Array` | Data to write |
 
-### writeToStreamMulti()
+### writeMulti()
 
-Write multiple chunks in a single operation. Optional optimization — not all World implementations support it. Falls back to sequential `writeToStream()` calls if unavailable.
+Write multiple chunks in a single operation. Optional optimization — not all World implementations support it. Falls back to sequential `write()` calls if unavailable.
 
 ```typescript lineNumbers
-await world.writeToStreamMulti?.("default", runId, [chunk1, chunk2]); // [!code highlight]
+await world.streams.writeMulti?.(runId, "default", [chunk1, chunk2]); // [!code highlight]
 ```
 
 **Parameters:**
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `name` | `string` | The stream name |
 | `runId` | `string` | The workflow run ID |
+| `name` | `string` | The stream name |
 | `chunks` | `(string \| Uint8Array)[]` | Chunks to write, in order |
 
-### readFromStream()
+### get()
 
 Read data from a named stream as a live `ReadableStream` that waits for new chunks in real time.
 
 ```typescript lineNumbers
-const readable = await world.readFromStream("default"); // [!code highlight]
+const readable = await world.streams.get(runId, "default"); // [!code highlight]
 ```
 
 **Parameters:**
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
+| `runId` | `string` | The workflow run ID |
 | `name` | `string` | The stream name |
 | `startIndex` | `number` | Optional. Positive values skip chunks from the start (0-based). Negative values read from the tail (e.g. `-3` starts 3 chunks from the end). Clamped to 0. |
 
 **Returns:** `ReadableStream<Uint8Array>`
 
-### closeStream()
+### close()
 
 Close a stream when done writing.
 
 ```typescript lineNumbers
-await world.closeStream("default", runId); // [!code highlight]
+await world.streams.close(runId, "default"); // [!code highlight]
 ```
 
 **Parameters:**
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `name` | `string` | The stream name |
 | `runId` | `string` | The workflow run ID |
+| `name` | `string` | The stream name |
 
-### listStreamsByRunId()
+### list()
 
 List all stream names associated with a workflow run.
 
 ```typescript lineNumbers
-const streamNames = await world.listStreamsByRunId(runId); // [!code highlight]
+const streamNames = await world.streams.list(runId); // [!code highlight]
 ```
 
 **Parameters:**
@@ -118,12 +119,12 @@ const streamNames = await world.listStreamsByRunId(runId); // [!code highlight]
 
 **Returns:** `string[]`
 
-### getStreamChunks()
+### getChunks()
 
-Fetch stream chunks with cursor-based pagination. Unlike `readFromStream()` (which returns a live `ReadableStream`), this returns a snapshot of currently available chunks.
+Fetch stream chunks with cursor-based pagination. Unlike `get()` (which returns a live `ReadableStream`), this returns a snapshot of currently available chunks.
 
 ```typescript lineNumbers
-const result = await world.getStreamChunks("default", runId, { // [!code highlight]
+const result = await world.streams.getChunks(runId, "default", { // [!code highlight]
   limit: 50,
 }); // [!code highlight]
 // result.data: StreamChunk[], result.cursor, result.hasMore, result.done
@@ -133,8 +134,8 @@ const result = await world.getStreamChunks("default", runId, { // [!code highlig
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `name` | `string` | The stream name |
 | `runId` | `string` | The workflow run ID |
+| `name` | `string` | The stream name |
 | `options.limit` | `number` | Max chunks per page (default: 100, max: 1000) |
 | `options.cursor` | `string` | Cursor from a previous response |
 
@@ -147,12 +148,12 @@ const result = await world.getStreamChunks("default", runId, { // [!code highlig
 | `hasMore` | `boolean` | Whether more pages of already-written chunks exist |
 | `done` | `boolean` | Whether the stream is fully closed. When `false`, new chunks may appear in future requests even after `hasMore` is `false`. |
 
-### getStreamInfo()
+### getInfo()
 
 Retrieve lightweight metadata about a stream without fetching chunks.
 
 ```typescript lineNumbers
-const info = await world.getStreamInfo("default", runId); // [!code highlight]
+const info = await world.streams.getInfo(runId, "default"); // [!code highlight]
 // info.tailIndex: last chunk index (-1 if empty), info.done: whether stream is closed
 ```
 
@@ -160,8 +161,8 @@ const info = await world.getStreamInfo("default", runId); // [!code highlight]
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `name` | `string` | The stream name |
 | `runId` | `string` | The workflow run ID |
+| `name` | `string` | The stream name |
 
 **Returns:** `StreamInfoResponse`
 
@@ -181,8 +182,9 @@ import { getWorld } from "workflow/runtime";
 export async function GET(req: Request) {
   const url = new URL(req.url);
   const streamName = url.searchParams.get("name") ?? "default";
-  const world = getWorld();
-  const readable = await world.readFromStream(streamName); // [!code highlight]
+  const runId = url.searchParams.get("runId")!;
+  const world = await getWorld();
+  const readable = await world.streams.get(runId, streamName); // [!code highlight]
 
   return new Response(readable, {
     headers: { "Content-Type": "application/octet-stream" },
@@ -195,11 +197,11 @@ export async function GET(req: Request) {
 ```typescript lineNumbers
 import { getWorld } from "workflow/runtime";
 
-const world = getWorld();
+const world = await getWorld();
 let cursor: string | undefined;
 
 do {
-  const result = await world.getStreamChunks("default", runId, { cursor }); // [!code highlight]
+  const result = await world.streams.getChunks(runId, "default", { cursor }); // [!code highlight]
   for (const chunk of result.data) {
     console.log(`Chunk ${chunk.index}:`, chunk.data);
   }

package/docs/cookbook/advanced/custom-serialization.mdx

@@ -0,0 +1,168 @@
+---
+title: Custom Serialization
+description: Make class instances serializable across workflow boundaries using the WORKFLOW_SERIALIZE and WORKFLOW_DESERIALIZE symbol protocol.
+type: guide
+summary: Implement the WORKFLOW_SERIALIZE and WORKFLOW_DESERIALIZE symbol protocol on classes so instances survive serialization when passed between workflow and step functions.
+---
+
+<Callout>
+This is an advanced guide. It dives into workflow internals and is not required reading to use workflow.
+</Callout>
+
+## The Problem
+
+Workflow functions run inside a sandboxed VM. Every value that crosses a function boundary — step arguments, step return values, workflow inputs — must be [serializable](/docs/foundations/serialization). Plain objects, strings, numbers, and many built-in types (`Date`, `Map`, `Set`, `RegExp`, etc.) work automatically, but **class instances** that don't implement the custom class serialization protocol will throw a serialization error.
+
+```typescript lineNumbers
+class StorageClient {
+  constructor(private region: string) {}
+
+  async upload(key: string, body: Uint8Array) {
+    // ... uses this.region internally
+  }
+}
+
+export async function processFile(client: StorageClient) {
+  "use workflow";
+
+  // client fails to serialize — StorageClient doesn't implement custom class serialization
+  // The runtime throws a serialization error
+  await uploadStep(client, "output.json", data);
+}
+```
+
+Custom class serialization solves this by teaching the runtime how to convert your class instances to plain data and back.
+
+## The WORKFLOW_SERIALIZE / WORKFLOW_DESERIALIZE Protocol
+
+The `@workflow/serde` package exports two symbols that act as a custom class serialization protocol. When the workflow runtime encounters a class instance with these symbols, it knows how to convert it to plain data and back.
+
+{/* @skip-typecheck - @workflow/serde is not mapped in the type-checker */}
+```typescript lineNumbers
+import { WORKFLOW_SERIALIZE, WORKFLOW_DESERIALIZE } from "@workflow/serde";
+
+class Point {
+  constructor(public x: number, public y: number) {}
+
+  distanceTo(other: Point): number {
+    return Math.sqrt((this.x - other.x) ** 2 + (this.y - other.y) ** 2);
+  }
+
+  static [WORKFLOW_SERIALIZE](instance: Point) { // [!code highlight]
+    return { x: instance.x, y: instance.y };
+  }
+
+  static [WORKFLOW_DESERIALIZE](data: { x: number; y: number }) { // [!code highlight]
+    return new Point(data.x, data.y);
+  }
+}
+```
+
+Both methods must be **static**. `WORKFLOW_SERIALIZE` receives an instance and returns plain serializable data. `WORKFLOW_DESERIALIZE` receives that same data and reconstructs a new instance.
+
+<Callout type="warn">
+Both serialization methods run inside the workflow VM. They must not use Node.js APIs, non-deterministic operations, or network calls. Keep them focused on extracting and reconstructing data.
+</Callout>
+
+## Automatic Class Registration
+
+For the runtime to deserialize a class, the class must be registered in a global registry with a stable `classId`. The SWC compiler plugin handles this automatically — when it detects a class with both `WORKFLOW_SERIALIZE` and `WORKFLOW_DESERIALIZE` static methods, it generates registration code at build time.
+
+This means you only need to implement the two symbol methods. The compiler assigns a deterministic `classId` based on the file path and class name, and registers it in the global `Symbol.for("workflow-class-registry")` registry.
+
+<Callout type="info">
+No manual registration is required for classes defined in your workflow files. The SWC plugin detects the serialization symbols and generates the registration automatically at build time.
+</Callout>
+
+## Full Example: A Workflow-Safe Storage Client
+
+Here's a complete example of a storage client class that survives serialization across workflow boundaries. This pattern is useful when you need an object with methods to be passed as a workflow input or returned from a step.
+
+```typescript lineNumbers
+import { WORKFLOW_SERIALIZE, WORKFLOW_DESERIALIZE } from "@workflow/serde";
+
+interface StorageClientOptions {
+  region: string;
+  bucket: string;
+  accessKeyId?: string;
+  secretAccessKey?: string;
+}
+
+export class WorkflowStorageClient {
+  private readonly region: string;
+  private readonly bucket: string;
+  private readonly accessKeyId?: string;
+  private readonly secretAccessKey?: string;
+
+  constructor(options: StorageClientOptions) {
+    this.region = options.region;
+    this.bucket = options.bucket;
+    this.accessKeyId = options.accessKeyId;
+    this.secretAccessKey = options.secretAccessKey;
+  }
+
+  async upload(key: string, body: Uint8Array) {
+    "use step";
+    const { S3Client, PutObjectCommand } = await import("@aws-sdk/client-s3");
+    const client = new S3Client({
+      region: this.region,
+      credentials: this.accessKeyId
+        ? { accessKeyId: this.accessKeyId, secretAccessKey: this.secretAccessKey! }
+        : undefined,
+    });
+    await client.send(
+      new PutObjectCommand({ Bucket: this.bucket, Key: key, Body: body })
+    );
+  }
+
+  async getSignedUrl(key: string): Promise<string> {
+    "use step";
+    const { S3Client, GetObjectCommand } = await import("@aws-sdk/client-s3");
+    const { getSignedUrl } = await import("@aws-sdk/s3-request-presigner");
+    const client = new S3Client({ region: this.region });
+    return getSignedUrl(client, new GetObjectCommand({ Bucket: this.bucket, Key: key }));
+  }
+
+  // --- Serialization protocol ---
+
+  static [WORKFLOW_SERIALIZE](instance: WorkflowStorageClient): StorageClientOptions { // [!code highlight]
+    return {
+      region: instance.region,
+      bucket: instance.bucket,
+      accessKeyId: instance.accessKeyId,
+      secretAccessKey: instance.secretAccessKey,
+    };
+  }
+
+  static [WORKFLOW_DESERIALIZE]( // [!code highlight]
+    data: StorageClientOptions
+  ): WorkflowStorageClient {
+    return new WorkflowStorageClient(data);
+  }
+}
+```
+
+Now this client can be passed into a workflow and used directly:
+
+```typescript lineNumbers
+import { WorkflowStorageClient } from "./storage-client";
+
+export async function processUpload(
+  client: WorkflowStorageClient,
+  data: Uint8Array
+) {
+  "use workflow";
+
+  // client is a real WorkflowStorageClient with working methods
+  await client.upload("output/result.json", data); // [!code highlight]
+  const url = await client.getSignedUrl("output/result.json"); // [!code highlight]
+  return { url };
+}
+```
+
+## Key APIs
+
+- [`WORKFLOW_SERIALIZE`](/docs/api-reference/workflow-serde/workflow-serialize) — symbol for the static serialization method
+- [`WORKFLOW_DESERIALIZE`](/docs/api-reference/workflow-serde/workflow-deserialize) — symbol for the static deserialization method
+- [`"use step"`](/docs/api-reference/workflow/use-step) — marks a function for extraction and serialization
+- [`"use workflow"`](/docs/api-reference/workflow/use-workflow) — declares the orchestrator function

package/docs/cookbook/advanced/durable-objects.mdx

@@ -0,0 +1,148 @@
+---
+title: Durable Objects
+description: Model long-lived stateful entities as workflows that persist state across requests.
+type: guide
+summary: Build a durable counter or session object whose state survives restarts by using a workflow's event log as the persistence layer.
+---
+
+<Callout>
+This is an advanced guide. It dives into workflow internals and is not required reading to use workflow.
+</Callout>
+
+## The Idea
+
+A workflow's event log already records every step result and replays them to reconstruct state. This is the same property that makes an "object" durable — its fields survive cold starts, crashes, and redeployments. Instead of using a workflow to model a *process*, you can use one to model an *entity* with methods.
+
+Each "method call" is a hook that the object's workflow loop awaits. External callers resume the hook with a payload describing the operation. The workflow applies the operation, updates its internal state, and waits for the next call.
+
+## Pattern: Durable Counter
+
+A counter that persists its value without a database. Each increment/decrement is recorded in the event log.
+
+```typescript lineNumbers
+import { defineHook, getWorkflowMetadata } from "workflow";
+import { z } from "zod";
+
+const counterAction = defineHook({ // [!code highlight]
+  schema: z.object({
+    type: z.enum(["increment", "decrement", "get"]),
+    amount: z.number().default(1),
+  }),
+});
+
+export async function durableCounter() {
+  "use workflow";
+
+  let count = 0;
+  const { workflowRunId } = getWorkflowMetadata();
+
+  while (true) {
+    const hook = counterAction.create({ token: `counter:${workflowRunId}` });
+    const action = await hook; // [!code highlight]
+
+    switch (action.type) {
+      case "increment":
+        count += action.amount;
+        await recordState(count);
+        break;
+      case "decrement":
+        count -= action.amount;
+        await recordState(count);
+        break;
+      case "get":
+        await emitValue(count);
+        break;
+    }
+  }
+}
+
+async function recordState(count: number) {
+  "use step";
+  // Step records the state transition in the event log.
+  // On replay, the step result restores `count` without re-executing.
+  return count;
+}
+
+async function emitValue(count: number) {
+  "use step";
+  return { count };
+}
+```
+
+### Calling the Object
+
+From an API route, resume the hook to "invoke a method" on the durable object:
+
+```typescript lineNumbers
+import { resumeHook } from "workflow/api";
+
+export async function POST(request: Request) {
+  const { runId, type, amount } = await request.json();
+  await resumeHook(`counter:${runId}`, { type, amount }); // [!code highlight]
+  return Response.json({ ok: true });
+}
+```
+
+## Pattern: Durable Session
+
+A chat session where conversation history is the durable state. Each user message is a hook event; the workflow accumulates messages and generates responses.
+
+```typescript lineNumbers
+import { defineHook, getWritable, getWorkflowMetadata } from "workflow";
+import { DurableAgent } from "@workflow/ai/agent";
+import { anthropic } from "@workflow/ai/anthropic";
+import { z } from "zod";
+import type { UIMessageChunk, ModelMessage } from "ai";
+
+const messageHook = defineHook({ // [!code highlight]
+  schema: z.object({
+    role: z.literal("user"),
+    content: z.string(),
+  }),
+});
+
+export async function durableSession() {
+  "use workflow";
+
+  const writable = getWritable<UIMessageChunk>();
+  const { workflowRunId: runId } = getWorkflowMetadata();
+  const messages: ModelMessage[] = [];
+
+  const agent = new DurableAgent({
+    model: anthropic("claude-sonnet-4-20250514"),
+    instructions: "You are a helpful assistant.",
+  });
+
+  while (true) {
+    const hook = messageHook.create({ token: `session:${runId}` });
+    const userMessage = await hook; // [!code highlight]
+
+    messages.push({
+      role: userMessage.role,
+      content: userMessage.content,
+    });
+
+    await agent.stream({ messages, writable });
+  }
+}
+```
+
+## When to Use This
+
+- **Entity-per-workflow**: Each user, document, or device gets its own workflow run. The run ID is the entity ID.
+- **No external database needed**: State lives in the event log. Reads replay from the log; writes append to it.
+- **Automatic consistency**: Only one execution runs at a time per workflow run, so there are no race conditions on the entity's state.
+
+## Trade-offs
+
+- **Read latency**: Accessing current state requires replaying the event log (or caching the last known state in a step result).
+- **Not a replacement for databases**: If you need to query across entities (e.g., "all counters above 100"), you still need a database. Durable objects are for single-entity state.
+- **Log growth**: Long-lived objects accumulate large event logs. Consider periodic "snapshot" steps that checkpoint the full state.
+
+## Key APIs
+
+- [`"use workflow"`](/docs/api-reference/workflow/use-workflow) — declares the orchestrator function
+- [`"use step"`](/docs/api-reference/workflow/use-step) — marks functions for durable execution
+- [`defineHook`](/docs/api-reference/workflow/define-hook) — type-safe hook for receiving external method calls
+- [`getWorkflowMetadata`](/docs/api-reference/workflow/get-workflow-metadata) — access the run ID for deterministic hook tokens
+- [`resumeHook`](/docs/api-reference/workflow-api/resume-hook) — invoke a method on the durable object from an API route

package/docs/cookbook/advanced/isomorphic-packages.mdx

@@ -0,0 +1,145 @@
+---
+title: Isomorphic Packages
+description: Publish reusable workflow packages that work both inside and outside the workflow runtime.
+type: guide
+summary: Use try/catch around getWorkflowMetadata, dynamic imports, and optional peer dependencies to build libraries that run in workflows and in plain Node.js.
+---
+
+<Callout>
+This is an advanced guide. It dives into workflow internals and is not required reading to use workflow.
+</Callout>
+
+## The Challenge
+
+If you're a library author publishing a package that integrates with workflow, your code needs to handle two environments:
+
+1. **Inside a workflow run** — `getWorkflowMetadata()` works, `"use step"` directives are transformed, and the full workflow runtime is available.
+2. **Outside a workflow** — your package is imported in a regular Node.js process, a test suite, or a project that doesn't use workflow at all.
+
+A hard dependency on `workflow` will crash at import time for users who don't have it installed.
+
+## Pattern 1: Feature-Detect with `getWorkflowMetadata`
+
+Use a try/catch to detect whether you're running inside a workflow. This lets you add durable behavior when available and fall back to standard execution otherwise.
+
+```typescript lineNumbers
+import { getWorkflowMetadata } from "workflow";
+
+export async function processPayment(amount: number, currency: string) {
+  "use workflow";
+
+  let runId: string | undefined;
+  try {
+    const metadata = getWorkflowMetadata(); // [!code highlight]
+    runId = metadata.workflowRunId;
+  } catch {
+    // Not running inside a workflow — proceed without durability
+    runId = undefined;
+  }
+
+  if (runId) {
+    // Inside a workflow: use the run ID as an idempotency key
+    return await chargeWithIdempotency(amount, currency, runId); // [!code highlight]
+  } else {
+    // Outside a workflow: standard charge
+    return await chargeStandard(amount, currency);
+  }
+}
+
+async function chargeWithIdempotency(amount: number, currency: string, idempotencyKey: string) {
+  "use step";
+  // Stripe charge with idempotency key from workflow run ID
+  return { charged: true, amount, currency, idempotencyKey };
+}
+
+async function chargeStandard(amount: number, currency: string) {
+  "use step";
+  return { charged: true, amount, currency };
+}
+```
+
+## Pattern 2: Dynamic Imports
+
+Avoid importing `workflow` at the top level. Use dynamic `import()` so the module is only loaded when actually needed.
+
+```typescript lineNumbers
+export async function createDurableTask(name: string, payload: unknown) {
+  "use workflow";
+
+  let sleep: ((duration: string) => Promise<void>) | undefined;
+
+  try {
+    const wf = await import("workflow"); // [!code highlight]
+    sleep = wf.sleep;
+  } catch {
+    // workflow not installed — use setTimeout fallback
+    sleep = undefined;
+  }
+
+  await executeTask(name, payload);
+
+  if (sleep) {
+    // Inside workflow: durable sleep that survives restarts
+    await sleep("5m"); // [!code highlight]
+  } else {
+    // Outside workflow: plain timer (not durable)
+    await new Promise((resolve) => setTimeout(resolve, 5 * 60 * 1000));
+  }
+
+  await sendNotification(name);
+}
+
+async function executeTask(name: string, payload: unknown) {
+  "use step";
+  return { executed: true, name, payload };
+}
+
+async function sendNotification(name: string) {
+  "use step";
+  return { notified: true, name };
+}
+```
+
+## Pattern 3: Optional Peer Dependencies
+
+In your `package.json`, declare `workflow` as an optional peer dependency. This signals to package managers that your library *can* use workflow but doesn't require it.
+
+```json
+{
+  "name": "@acme/payments",
+  "peerDependencies": {
+    "workflow": ">=1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "workflow": {
+      "optional": true
+    }
+  }
+}
+```
+
+Then guard all workflow imports with dynamic `import()` and try/catch as shown above.
+
+## Real-World Examples
+
+### Mux AI
+
+The Mux team published a reusable workflow package for video processing. Their library detects the workflow runtime and falls back to standard async processing when workflow isn't available.
+
+### World ID
+
+World ID's identity verification library uses `getWorkflowMetadata()` to attach run IDs to their human-in-the-loop verification hooks, but the same library works in non-workflow environments for simple verification flows.
+
+## Guidelines for Library Authors
+
+1. **Never hard-import `workflow` at the top level** if your package should work without it.
+2. **Use `getWorkflowMetadata()` in a try/catch** as the canonical runtime detection pattern.
+3. **Mark `workflow` as an optional peer dependency** in `package.json`.
+4. **Test both paths**: run your test suite with and without the workflow runtime to catch import errors.
+5. **Document the dual behavior**: make it clear in your README which features require workflow and which work standalone.
+
+## Key APIs
+
+- [`"use workflow"`](/docs/api-reference/workflow/use-workflow) — declares the orchestrator function
+- [`"use step"`](/docs/api-reference/workflow/use-step) — marks functions for durable execution
+- [`getWorkflowMetadata`](/docs/api-reference/workflow/get-workflow-metadata) — runtime detection and run ID access

package/docs/cookbook/advanced/meta.json

@@ -0,0 +1,10 @@
+{
+  "title": "Advanced",
+  "pages": [
+    "serializable-steps",
+    "durable-objects",
+    "isomorphic-packages",
+    "custom-serialization",
+    "publishing-libraries"
+  ]
+}