@workflow/core 5.0.0-beta.35 → 5.0.0-beta.37

package/docs/api-reference/create-hook.mdx

@@ -66,7 +66,7 @@ export default Hook;`}
 
 The returned `Hook` object also implements `AsyncIterable<T>`, which allows you to iterate over incoming payloads using `for await...of` syntax.
 
-Use `hook.getConflict()` to check whether the hook token is already claimed by another active hook, without waiting for hook payload data. 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 registration, then resolves with `null` once `hook_created` is recorded, or with the conflicting [`Run`](/docs/api-reference/workflow-api/get-run) if another active hook already owns the same token.
+Use `hook.getConflict()` to check whether the hook token is already claimed by another hook, including one kept reserved after its run ends, without waiting for hook payload data. 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 registration, then resolves with `null` once `hook_created` is recorded, or with the conflicting [`Run`](/docs/api-reference/workflow-api/get-run).
 
 ## Examples
 
@@ -143,12 +143,53 @@ async function processOrder(orderId: string) {
 
 Because `createHook()` alone does not suspend the workflow, awaiting `hook.getConflict()` is what actually suspends the run and commits the hook registration. It only waits for registration — to receive payload data from a future `resumeHook()` call, await the hook itself or iterate it with `for await...of`.
 
-On a conflict, the resolved value is a `Run` handle for the run that currently owns the token, with durable step-backed accessors. The duplicate run can decide in code how to handle it: return or log `conflict.runId`, inspect `await conflict.status`, wait on `await conflict.returnValue`, or cancel the owner with `await conflict.cancel()` and continue in the current run. See [Run idempotency](/docs/foundations/idempotency#run-idempotency) for these strategies in context.
+On a conflict, the resolved value is a `Run` handle for the run that owns the token, with durable step-backed accessors. The duplicate run can decide in code how to handle it: return or log `conflict.runId`, inspect `await conflict.status`, wait on `await conflict.returnValue`, or cancel the owner with `await conflict.cancel()` and continue in the current run. See [Run idempotency](/docs/foundations/idempotency#run-idempotency) for these strategies in context.
 
 <Callout type="info">
 Custom hook tokens are the recommended way to coordinate active workflow runs. Use a deterministic token from your domain, such as an order ID or conversation ID, create the hook near the beginning of the workflow, and check `await hook.getConflict()` before work that depends on owning the token. See [Run idempotency](/docs/foundations/idempotency#run-idempotency).
 </Callout>
 
+### Keep a Token Unavailable After the Run Ends
+
+By default, another Hook can use the token after its workflow ends. Set `experimental_minRetention` to keep the token unavailable for at least a specific time after `createHook()` runs:
+
+```typescript lineNumbers
+import { createHook } from "workflow";
+
+declare function processOwnedOrder(orderId: string): Promise<void>; // @setup
+
+export async function processOrder(orderId: string) {
+  "use workflow";
+
+  const hook = createHook({ // [!code highlight]
+    token: `order:${orderId}`, // [!code highlight]
+    experimental_minRetention: "30d", // [!code highlight]
+  }); // [!code highlight]
+
+  const conflict = await hook.getConflict();
+  if (conflict) {
+    return { status: "duplicate" as const, runId: conflict.runId };
+  }
+
+  await processOwnedOrder(orderId);
+  return { status: "processed" as const };
+}
+```
+
+`experimental_minRetention` accepts the same values as [`sleep()`](/docs/api-reference/workflow/sleep): a duration string such as `"30d"`, a number of milliseconds, or an absolute `Date`. Durations start when `createHook()` runs.
+
+The Hook remains active until the workflow ends, even if the configured time passes first. Another Hook can use the token only after both the workflow has ended and the configured time has passed. For example, `"30d"` keeps the token unavailable for 29 more days if the workflow ends after 1 day. A workflow that runs for more than 30 days releases the token when it ends.
+
+After the workflow ends, [`getHookByToken()`](/docs/api-reference/workflow-api/get-hook-by-token) can still find the Hook until retention ends, but the Hook cannot be resumed.
+
+<Callout type="warn">
+`using` auto-disposes the Hook at scope exit, which releases the token immediately and defeats `experimental_minRetention`. Declare retained Hooks with `const` and let the runtime clean them up when the run ends.
+</Callout>
+
+<Callout type="warn">
+This option is experimental. If the configured World does not support it, the workflow fails when registering the Hook. `createWebhook()` does not accept this option.
+</Callout>
+
 ### Waiting for Multiple Payloads
 
 You can also wait for multiple payloads by using the `for await...of` syntax.

package/docs/api-reference/define-hook.mdx

@@ -46,24 +46,21 @@ showSections={['parameters']}
 
 ### Returns
 
+`defineHook()` returns a `TypedHook<TInput, TOutput>`:
+
 <TSDoc
 definition={`
-interface DefineHook<T> {
-  /**
-
-* Creates a new hook with the defined payload type.
-  */
-  create: (options?: HookOptions) => Hook<T>;
-
-  /**
-
-* Resumes a hook by sending a payload with the defined type.
-   */
-  resume: (token: string, payload: T) => Promise<HookEntity | null>;
+interface TypedHook<TInput, TOutput> {
+  /** Creates the hook. Call inside a "use workflow" function. */
+  create(options?: HookOptions): Hook<TOutput>;
+  /** Resumes the hook from runtime code. Resolves to the resumed hook; throws HookNotFoundError if the token does not match an active hook. */
+  resume(token: string, payload: TInput): Promise<HookEntity>;
 }
-export default DefineHook;`}
+export default TypedHook;`}
 />
 
+`create()` is called inside a `"use workflow"` function to create the hook; `resume()` is called from runtime code (an API route or server action). When a `schema` is provided, `resume()` accepts the raw input type (`TInput`) and the workflow receives the validated and possibly transformed output type (`TOutput`); without a schema, `TOutput` defaults to `TInput`. `resume()` throws [`HookNotFoundError`](/docs/api-reference/workflow-errors/hook-not-found-error) if the token does not match an active hook — it does not return `null`.
+
 ## Examples
 
 ### Basic Type-Safe Hook Definition
@@ -93,24 +90,29 @@ export async function workflowWithApproval() {
 
 ### Resuming with Type Safety
 
-Hooks can be resumed using the same defined hook and a token. By using the same hook, you can ensure that the payload matches the defined type when resuming a hook.
+Hooks can be resumed using the same defined hook and a token. By using the same hook, you can ensure that the payload matches the defined type when resuming a hook. `resume()` resolves to the resumed hook and throws [`HookNotFoundError`](/docs/api-reference/workflow-errors/hook-not-found-error) if the token does not match an active hook.
 
 ```typescript lineNumbers
+import { HookNotFoundError } from "workflow/errors";
+
 // Use the same defined hook to resume
 export async function POST(request: Request) {
   const { token, approved, comment } = await request.json();
 
-  // Type-safe resumption - TypeScript ensures the payload matches
-  const result = await approvalHook.resume(token, { // [!code highlight]
-    approved, // [!code highlight]
-    comment, // [!code highlight]
-  }); // [!code highlight]
-
-  if (!result) {
-    return Response.json({ error: "Hook not found" }, { status: 404 });
+  try {
+    // Type-safe resumption - TypeScript ensures the payload matches
+    const hook = await approvalHook.resume(token, { // [!code highlight]
+      approved, // [!code highlight]
+      comment, // [!code highlight]
+    }); // [!code highlight]
+
+    return Response.json({ success: true, runId: hook.runId });
+  } catch (error) {
+    if (HookNotFoundError.is(error)) { // [!code highlight]
+      return Response.json({ error: "Hook not found" }, { status: 404 });
+    }
+    throw error;
   }
-
-  return Response.json({ success: true, runId: result.runId });
 }
 ```
 

package/docs/api-reference/fatal-error.mdx

@@ -29,16 +29,38 @@ async function fallibleStep() {
 
 ## API Signature
 
-### Parameters
+### Constructor
+
+`new FatalError(message)`
+
+| Parameter | Type     | Description        |
+| --------- | -------- | ------------------ |
+| `message` | `string` | The error message. |
+
+### Properties
 
 <TSDoc
 definition={`
-interface Error {
-  /**
-
-* The error message.
-   */
+interface FatalError {
+  /** The error message. */
   message: string;
+  /** Always true. Marks the error as non-retryable. */
+  fatal: boolean;
 }
-export default Error;`}
+export default FatalError;`}
 />
+
+### Static Methods
+
+#### `FatalError.is(value)`
+
+Type-safe check for `FatalError` instances. Preferred over `instanceof` because it works across module boundaries and VM contexts.
+
+```typescript
+import { FatalError } from "workflow"
+declare const error: unknown; // @setup
+
+if (FatalError.is(error)) {
+  // error is typed as FatalError
+}
+```

package/docs/api-reference/fetch.mdx

@@ -93,7 +93,7 @@ This API is provided as a convenience to easily use `fetch` in workflow, but oft
 
 ### Customizing Fetch Behavior
 
-Here's an example of a custom fetch wrapper that provides more sophisticated error handling with custom retry logic:
+Here's an example of a custom fetch wrapper that provides more sophisticated error handling with custom retry logic. Call `globalThis.fetch` inside your own `"use step"` function — calling the workflow `fetch` imported from `workflow` would nest a step inside a step:
 
 ```typescript lineNumbers
 import { FatalError, RetryableError } from "workflow"
@@ -104,7 +104,7 @@ export async function customFetch(
 ) {
     "use step"
 
-    const response = await fetch(url, init)
+    const response = await globalThis.fetch(url, init)
 
     // Handle client errors (4xx) - don't retry
     if (response.status >= 400 && response.status < 500) {
@@ -145,7 +145,6 @@ export async function customFetch(
 
 This example demonstrates:
 
-- Setting custom `maxRetries` to 5 retries (6 total attempts including the initial attempt).
 - Throwing [`FatalError`](/docs/api-reference/workflow/fatal-error) for client errors (400-499) to prevent retries.
 - Handling 429 rate limiting by reading the `Retry-After` header and using [`RetryableError`](/docs/api-reference/workflow/retryable-error).
-- Allowing automatic retries for server errors (5xx).
+- Allowing automatic retries for server errors (5xx) by throwing a plain `Error`.

package/docs/api-reference/set-attributes.mdx

@@ -59,7 +59,3 @@ Validation errors throw [`FatalError`](/docs/api-reference/workflow/fatal-error)
 Calls from both workflow and step bodies append a native `attr_set` event, which the World materializes onto `run.attributes`. Workflow-originated events record a workflow writer; step-originated events record the originating step ID and attempt.
 
 Native attributes require spec version 4 or later. Step-body storage errors throw from `setAttributes`; catch them inside the step if the write should be best-effort. Workflow-body writes are committed when the workflow suspends: transient storage errors are retried with the suspension, while a write the World rejects as invalid — such as exceeding the per-run attribute cap across multiple calls — fails the run with the validation error.
-
-<Callout>
-This function was previously exported as `experimental_setAttributes`. The old name still works as a deprecated alias — update imports to `setAttributes`.
-</Callout>

package/docs/api-reference/sleep.mdx

@@ -14,7 +14,7 @@ Suspends a workflow for a specified duration or until an end date without consum
 This is useful when you want to resume a workflow after some duration or date.
 
 <Callout>
-`sleep` is a *special* type of step function and should be called directly inside workflow functions.
+`sleep` is a built-in workflow runtime function (backed by a timer event in the event log, not a step) and should be called directly inside workflow functions.
 </Callout>
 
 ```typescript lineNumbers

package/docs/foundations/hooks.mdx

@@ -112,7 +112,7 @@ export async function orderWorkflow(orderId: string) {
 }
 ```
 
-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 [Run idempotency](/docs/foundations/idempotency#run-idempotency) for these strategies.
+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 (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 [Run idempotency](/docs/foundations/idempotency#run-idempotency) for these strategies.
 
 ### Custom Tokens for Deterministic Hooks
 

package/docs/foundations/idempotency.mdx

@@ -96,7 +96,7 @@ export async function processOrder(orderId: string): Promise<OrderResult> {
 }
 ```
 
-The runtime creates the hook atomically. At most one active hook can own `order:${orderId}`, so duplicate workflow runs converge on one active owner. A duplicate run observes `getConflict()` resolving with the owner's `Run` and returns before it reaches `chargeOrder()`. The conflicting run's accessors (`status`, `returnValue`, `cancel()`, …) are durable steps, so the duplicate run can do more than report the owner — see [conflict-handling strategies](#conflict-handling-strategies) below.
+The runtime creates the hook atomically. At most one hook can own `order:${orderId}`, so duplicate workflow runs converge on one owner. A duplicate run observes `getConflict()` resolving with the owner's `Run` and returns before it reaches `chargeOrder()`. The conflicting run's accessors (`status`, `returnValue`, `cancel()`, …) are durable steps, so the duplicate run can do more than report the owner — see [conflict-handling strategies](#conflict-handling-strategies) below.
 
 Outside the workflow, try to resume the hook first. If the hook is not registered yet, start the workflow and retry the resume until the new run creates the hook:
 
@@ -149,7 +149,7 @@ export async function POST(request: Request) {
 This avoids creating a new run only after the first run has registered its hook. Because `start()` returns before the run body executes and calls `createHook()`, two concurrent requests can both observe "no hook yet" and each call `start()`. The race is resolved inside the workflow body, where the losing run observes `getConflict()` resolving with the active owner and returns without doing duplicate-sensitive work — and the route detects it by comparing the resumed hook's `runId` against the run it just started, without waiting for either run to finish. A native API for atomically starting a run and registering a hook is in the works. Until then, model recovery inside the workflow by checking `hook.getConflict()`.
 </Callout>
 
-This is active-run coordination. When the workflow completes and disposes the hook, the token can be used again. If a duplicate request after completion must return the original result instead of starting fresh work, persist that completed result under the same domain key.
+This coordinates active runs by default: the token becomes available when its workflow ends. Set `experimental_minRetention` to keep it unavailable to late duplicates. After the workflow ends, the Hook can still be found with `getHookByToken()` until retention ends, but it cannot be resumed. See [`createHook()` minimum retention](/docs/api-reference/workflow/create-hook#keep-a-token-unavailable-after-the-run-ends) for examples and supported values.
 
 ### Conflict-handling strategies
 
@@ -182,7 +182,7 @@ export async function processOrder(orderId: string) {
 }
 ```
 
-**Inspect the owner before deciding.** Branch on the owner's live state:
+**Inspect the owner before deciding.** Reuse a completed owner's result, but reject other duplicates:
 
 ```typescript lineNumbers
 import { createHook } from "workflow";
@@ -200,17 +200,17 @@ export async function processOrder(orderId: string) {
   const conflict = await request.getConflict();
   if (conflict) {
     const status = await conflict.status; // [!code highlight]
-    if (status === "running") {
-      return { status: "duplicate" as const, runId: conflict.runId };
+    if (status === "completed") {
+      return await conflict.returnValue;
     }
-    // Owner already reached a terminal state; its hook will be released.
+    return { status: "duplicate" as const, runId: conflict.runId };
   }
 
   return await processOwnedOrder(orderId);
 }
 ```
 
-**Signal the owner instead of doing the work.** The duplicate run knows the token, so it can deliver this run's input to the owner's hook from a step:
+**Signal the owner instead of doing the work.** A conflict can refer to a finished run when `experimental_minRetention` is set, so check its status before sending data to its Hook:
 
 ```typescript lineNumbers
 import { createHook } from "workflow";
@@ -230,16 +230,19 @@ export async function processOrder(orderId: string, confirmed: boolean) {
   using request = createHook<OrderRequest>({ token });
 
   const conflict = await request.getConflict();
-  if (conflict) {
+  if (conflict && ["pending", "running"].includes(await conflict.status)) {
     await forwardToOwner(token, { confirmed }); // [!code highlight]
     return { status: "forwarded" as const, runId: conflict.runId };
   }
+  if (conflict) {
+    return { status: "duplicate" as const, runId: conflict.runId };
+  }
 
   // ... own the token and do the work
 }
 ```
 
-**Supersede the owner.** Newest-wins: cancel the active run, then claim the released token. Cancellation disposes the owner's hooks; the retry loop covers the window where that disposal has not propagated yet:
+**Supersede the owner.** Without minimum retention, cancel the active run, then claim the released token. The retry loop covers the window where cancellation cleanup has not propagated yet:
 
 ```typescript lineNumbers
 import { createHook } from "workflow";
@@ -272,6 +275,10 @@ export async function processOrderNewestWins(orderId: string) {
 }
 ```
 
+<Callout type="warn">
+This pattern does not work with `experimental_minRetention`: cancelling the old run does not make its token available early.
+</Callout>
+
 If duplicate requests should only reuse the active run without sending data, use [`getHookByToken()`](/docs/api-reference/workflow-api/get-hook-by-token) as an advisory pre-check before calling `start()`. The workflow should still check `hook.getConflict()`, because the lookup and `start()` are not atomic.
 
 Because this pattern uses hooks for idempotency, duplicate requests can also inject additional data and steer the existing run. The route example above uses `resumeHook()` for that: if the hook already exists, the duplicate request resumes the active workflow; if the hook is not registered yet, the route starts the workflow and retries `resumeHook()` so the payload is not dropped.

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

@@ -176,12 +176,12 @@ The step's `ops` array is awaited via `waitUntil(Promise.all(ops))` after the st
 
 ### Abort Errors Are Wrapped in FatalError
 
-When a step throws due to an abort — whether from `fetch` throwing `AbortError`, `signal.throwIfAborted()`, or any other abort-induced error — the step handler wraps the error in `FatalError` before recording it in the event log. This ensures:
+When a step throws due to an abort — whether from `fetch` throwing `AbortError`, `signal.throwIfAborted()`, or any other abort-induced error — the step executor wraps the error in `FatalError` before recording it in the event log. This ensures:
 
 - **No retries**: An abort is intentional cancellation, not a transient failure. Retrying would just abort again.
 - **Immediate propagation**: The error bubbles up to the workflow as a `FatalError`, which the workflow can catch with `FatalError.is(err)`.
 
-The wrapping happens at the step handler level (`runtime/step-handler.ts`), during error hydration. When the step's thrown error is an `AbortError` (checked via `err.name === 'AbortError'`), it is treated as fatal regardless of the step's `maxRetries` configuration.
+The wrapping happens in `runtime/step-executor.ts` during error hydration. When the step's thrown error is an `AbortError` (checked via `err.name === 'AbortError'`), it is treated as fatal regardless of the step's `maxRetries` configuration.
 
 ### abort() in the Workflow
 

package/docs/how-it-works/code-transform.mdx

@@ -53,18 +53,20 @@ flowchart LR
     A["Source Code<br/>with directives"] --> B["Step Mode"]
     A --> C["Workflow Mode"]
     A --> D["Client Mode"]
-    B --> E["step.js<br/>(Step Execution)"]
-    C --> F["flow.js<br/>(Workflow Execution)"]
+    B --> E["Step registration bundle"]
+    C --> F["Workflow bundle"]
+    E --> H["Combined flow handler"]
+    F --> H
     D --> G["Your App Code<br/>(Enables `start`)"]
 ```
 
 ### Comparison Table
 
-| Mode     | Used In    | Purpose                        | Output API Route                   | Required? |
-|----------|------------|--------------------------------|------------------------------------|-----------|
-| Step     | Build time | Bundles step handlers          | `.well-known/workflow/v1/step`  | Yes       |
-| Workflow | Build time | Bundles workflow orchestrators | `.well-known/workflow/v1/flow`  | Yes       |
-| Client   | Build/Runtime | Provides workflow IDs and types to `start`   | Your application code              | Optional* |
+| Mode     | Used In    | Purpose                        | Runtime role | Required? |
+|----------|------------|--------------------------------|--------------|-----------|
+| Step     | Build time | Registers executable step functions | Imported by the combined flow handler | Yes |
+| Workflow | Build time | Bundles workflow orchestrators | Executed by `.well-known/workflow/v1/flow` | Yes |
+| Client   | Build/Runtime | Provides workflow IDs and types to `start` | Your application code | Optional* |
 
 \* Client mode is **recommended** for better developer experience—it provides automatic ID generation and type safety. Without it, you must manually construct workflow IDs or use the build manifest.
 
@@ -73,7 +75,7 @@ flowchart LR
 <Tabs items={["Step Mode", "Workflow Mode", "Client Mode"]}>
 <Tab value="Step Mode">
 
-**Step Mode** creates the step execution bundle served at `/.well-known/workflow/v1/step`.
+**Step Mode** creates a registration bundle that the combined flow handler imports. It is not an HTTP route.
 
 **Input:**
 
@@ -211,7 +213,7 @@ The IDs are generated exactly like in workflow mode to ensure they can be direct
 
 ## Generated Files
 
-When you build your application, the Workflow SDK generates three handler files in `.well-known/workflow/v1/`:
+When you build your application, the Workflow SDK generates a combined flow handler, an internal step registration bundle, and a webhook handler. Exact filenames vary by framework.
 
 ### `flow.js`
 
@@ -245,15 +247,17 @@ Most invalid patterns cause **build-time errors**, catching issues before deploy
   **Why a VM?** Workflow functions must be deterministic to support replay. The VM sandbox prevents accidental use of non-deterministic APIs or side effects. All side effects should be performed in [step functions](/docs/foundations/workflows-and-steps#step-functions) instead.
 </Callout>
 
-### `step.js`
+### `__step_registrations.js`
 
-Contains all step functions transformed in **step mode**. This file is imported by your framework to handle step execution requests at `POST /.well-known/workflow/v1/step`.
+Contains all step functions transformed in **step mode**. The combined flow handler imports this module for its registration side effects.
 
 **What it does:**
 
-- Exports a `POST` handler that accepts Web standard `Request` objects
-- Executes individual steps with full runtime access
-- Returns step results to the orchestration layer
+- Adds step functions to the runtime step registry
+- Keeps step bodies in the full host runtime
+- Makes registered steps available when a flow queue message includes `stepId` and `stepName`
+
+This module must not be exposed as an HTTP endpoint.
 
 ### `webhook.js`
 
@@ -336,7 +340,7 @@ These transformations are framework-agnostic—they output standard JavaScript t
 
 If you need to debug transformation issues, you can inspect the generated files:
 
-1. **Look in `.well-known/workflow/v1/`**: Check the generated `flow.js`, `step.js`,`webhook.js`, and other emitted debug files.
+1. **Inspect the generated output**: Check the combined flow handler, step registration bundle, webhook handler, and emitted debug files.
 2. **Check build logs**: Most frameworks log transformation activity during builds
 3. **Verify directives**: Ensure `"use workflow"` and `"use step"` are the first statements in functions
 4. **Check file locations**: Transformations only apply to files in configured source directories

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

@@ -7,7 +7,7 @@ prerequisites:
   - /docs/how-it-works/event-sourcing
 related:
   - /docs/observability
-  - /docs/deploying/world/vercel-world
+  - /worlds/vercel
 ---
 
 <Callout>
@@ -38,7 +38,7 @@ Metadata such as workflow names, step names, entity IDs, timestamps, and lifecyc
 
 Each workflow run is encrypted with its own unique key, provided by the `World` implementation via `getEncryptionKeyForRun()`. How the key is generated and stored is up to the `World`.
 
-For example, the [Vercel World](/docs/deploying/world/vercel-world) provides unique keys per run and execution environment, ensuring that a given run can only decrypt data from that run itself.
+For example, the [Vercel World](/worlds/vercel) provides unique keys per run and execution environment, ensuring that a given run can only decrypt data from that run itself.
 
 ### Encryption Algorithm
 
@@ -127,4 +127,4 @@ async function lookupRunKey(
 }
 ```
 
-The [Vercel World](/docs/deploying/world/vercel-world) implementation uses HKDF derivation from a deployment-scoped key, but any consistent key management scheme will work.
+The [Vercel World](/worlds/vercel) implementation uses HKDF derivation from a deployment-scoped key, but any consistent key management scheme will work.

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

@@ -121,15 +121,15 @@ flowchart TD
 
 **Hook states:**
 
-- `active`: Ready to receive payloads (hook exists in storage)
-- `disposed`: No longer accepting payloads (hook is deleted from storage)
+- `active`: Ready to receive payloads
+- `disposed`: No longer accepting payloads
 - `conflicted`: Hook creation failed because the token is already in use by another workflow
 
-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.
+Unlike other entities, hooks don't have a `status` field—the states above are conceptual. 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 `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.
+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 reserved by another run — either by an active hook or by `experimental_minRetention` after its run ended — a `hook_conflict` event is recorded instead of `hook_created`. Current worlds include the token and the run ID that 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.
+When a workflow ends, its Hooks can no longer be resumed. They are normally removed and their tokens become available again. With `experimental_minRetention`, a Hook remains readable and its token remains unavailable until retention ends. A `hook_disposed` event removes the Hook and makes its token available immediately.
 
 See [Hooks & Webhooks](/docs/foundations/hooks) for more on how hooks and webhooks work.
 
@@ -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: `hook.getConflict()` resolves with the conflicting run, and awaiting the hook payload rejects with a `HookConflictError`. |
+| `hook_conflict` | Records that hook creation failed because another run owns the token. Contains the token and, for current worlds, the 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. |