workflow 5.0.0-beta.9 → 5.0.1

package/docs/api-reference/workflow-errors/run-expired-error.mdx

@@ -29,7 +29,7 @@ try {
 }
 ```
 
-## API Signature
+## API signature
 
 ### Properties
 
@@ -42,7 +42,7 @@ interface RunExpiredError {
 export default RunExpiredError;`}
 />
 
-### Static Methods
+### Static methods
 
 #### `RunExpiredError.is(value)`
 

package/docs/api-reference/workflow-errors/run-not-supported-error.mdx

@@ -0,0 +1,58 @@
+---
+title: RunNotSupportedError
+description: Thrown when a workflow run requires a newer workflow spec version than the installed SDK supports.
+type: reference
+summary: Catch RunNotSupportedError when stored run data requires a newer workflow package version.
+related:
+  - /docs/foundations/versioning
+---
+
+`RunNotSupportedError` is thrown when reading a workflow run whose data was written with a newer workflow spec version than the running SDK supports. This typically means the run was created by a newer version of the `workflow` package. Upgrade the package to process it.
+
+```typescript lineNumbers
+import { RunNotSupportedError } from "workflow/errors"
+declare function readRun(runId: string): Promise<unknown>; // @setup
+declare const runId: string; // @setup
+
+try {
+  await readRun(runId);
+} catch (error) {
+  if (RunNotSupportedError.is(error)) { // [!code highlight]
+    console.error(
+      `Run requires spec v${error.runSpecVersion}, world supports v${error.worldSpecVersion}`
+    );
+  }
+}
+```
+
+## API signature
+
+### Properties
+
+<TSDoc
+definition={`
+interface RunNotSupportedError {
+  /** The spec version the run's stored data requires. */
+  runSpecVersion: number;
+  /** The spec version the current World supports. */
+  worldSpecVersion: number;
+  /** The error message. */
+  message: string;
+}
+export default RunNotSupportedError;`}
+/>
+
+### Static methods
+
+#### `RunNotSupportedError.is(value)`
+
+Type-safe check for `RunNotSupportedError` instances. Preferred over `instanceof` because it works across module boundaries and virtual machine contexts.
+
+```typescript
+import { RunNotSupportedError } from "workflow/errors"
+declare const error: unknown; // @setup
+
+if (RunNotSupportedError.is(error)) {
+  // error is typed as RunNotSupportedError
+}
+```

package/docs/api-reference/workflow-errors/step-not-registered-error.mdx

@@ -8,7 +8,7 @@ related:
   - /docs/api-reference/workflow-errors/workflow-not-registered-error
 ---
 
-`StepNotRegisteredError` is thrown when the runtime tries to execute a step function that is not registered in the current deployment. This is an infrastructure error — not a user code error. It typically indicates a build or bundling issue that caused the step to not be included in the deployment.
+`StepNotRegisteredError` is thrown when the runtime tries to execute a step function that is not registered in the current deployment. This is an infrastructure error, not a user code error. It typically indicates a build or bundling issue that caused the step to not be included in the deployment.
 
 When this error occurs, the step fails (like a `FatalError`) and control is passed back to the workflow function, which can handle the failure gracefully.
 
@@ -21,7 +21,7 @@ if (StepNotRegisteredError.is(error)) { // [!code highlight]
 }
 ```
 
-## API Signature
+## API signature
 
 ### Properties
 
@@ -36,14 +36,14 @@ interface StepNotRegisteredError {
 export default StepNotRegisteredError;`}
 />
 
-### Static Methods
+### Static methods
 
 #### `StepNotRegisteredError.is(value)`
 
-Type-safe check for `StepNotRegisteredError` instances. Preferred over `instanceof` because it works across module boundaries and VM contexts.
+Type-safe check for `StepNotRegisteredError` instances. Preferred over `instanceof` because it works across module boundaries and virtual machine contexts.
 
 <Callout>
-The `.is()` method works in server-side Node.js code (API routes, middleware, hooks). Inside `"use workflow"` functions, step errors arrive deserialized from the event log and won't be actual `StepNotRegisteredError` instances — use `error.message` matching instead. See the [troubleshooting page](/docs/errors/step-not-registered) for workflow-side error handling examples.
+The `.is()` method works in server-side Node.js code (API routes, middleware, hooks). Inside `"use workflow"` functions, step errors arrive deserialized from the event log and won't be actual `StepNotRegisteredError` instances. Use `error.message` matching instead. See the [troubleshooting page](/docs/errors/step-not-registered) for workflow-side error handling examples.
 </Callout>
 
 ```typescript

package/docs/api-reference/workflow-errors/throttle-error.mdx

@@ -31,7 +31,7 @@ try {
 }
 ```
 
-## API Signature
+## API signature
 
 ### Properties
 
@@ -46,7 +46,7 @@ interface ThrottleError {
 export default ThrottleError;`}
 />
 
-### Static Methods
+### Static methods
 
 #### `ThrottleError.is(value)`
 

package/docs/api-reference/workflow-errors/too-early-error.mdx

@@ -31,7 +31,7 @@ try {
 }
 ```
 
-## API Signature
+## API signature
 
 ### Properties
 
@@ -46,7 +46,7 @@ interface TooEarlyError {
 export default TooEarlyError;`}
 />
 
-### Static Methods
+### Static methods
 
 #### `TooEarlyError.is(value)`
 

package/docs/api-reference/workflow-errors/workflow-error.mdx

@@ -0,0 +1,52 @@
+---
+title: WorkflowError
+description: Base class for all workflow error types.
+type: reference
+summary: All errors thrown by the Workflow SDK extend WorkflowError.
+related:
+  - /docs/foundations/errors-and-retries
+---
+
+`WorkflowError` is the base class that all Workflow SDK error types extend, such as [`WorkflowRunFailedError`](/docs/api-reference/workflow-errors/workflow-run-failed-error) and [`HookNotFoundError`](/docs/api-reference/workflow-errors/hook-not-found-error). It extends `Error` with an optional `cause` and, for some subclasses, a link to the relevant error documentation appended to the message.
+
+```typescript lineNumbers
+import { WorkflowError } from "workflow/errors"
+
+const error = new WorkflowError("something went wrong", {
+  cause: new Error("underlying cause"),
+});
+```
+
+## API signature
+
+### Properties
+
+<TSDoc
+definition={`
+interface WorkflowError {
+  /** The error message. */
+  message: string;
+  /** The underlying cause, when provided. */
+  cause?: unknown;
+}
+export default WorkflowError;`}
+/>
+
+### Static methods
+
+#### `WorkflowError.is(value)`
+
+Type-safe check for `WorkflowError` instances. Preferred over `instanceof` because it works across module boundaries and virtual machine contexts.
+
+<Callout type="warn">
+  `WorkflowError.is()` matches only direct `WorkflowError` instances, not subclasses, which override the error name it checks. To handle a specific error type, use that subclass's own `.is()` method (e.g. `WorkflowRunFailedError.is(error)`).
+</Callout>
+
+```typescript
+import { WorkflowError } from "workflow/errors"
+declare const error: unknown; // @setup
+
+if (WorkflowError.is(error)) {
+  // error is typed as WorkflowError
+}
+```

package/docs/api-reference/workflow-errors/workflow-not-registered-error.mdx

@@ -8,7 +8,7 @@ related:
   - /docs/api-reference/workflow-errors/step-not-registered-error
 ---
 
-`WorkflowNotRegisteredError` is thrown when the runtime tries to execute a workflow function that is not registered in the current deployment. This is an infrastructure error — not a user code error. It typically means a run was started against a deployment that does not have this workflow (e.g., the workflow was renamed or moved), or there was a build/bundling issue.
+`WorkflowNotRegisteredError` is thrown when the runtime tries to execute a workflow function that is not registered in the current deployment. This is an infrastructure error, not a user code error. It typically means a run was started against a deployment that does not have this workflow (e.g., the workflow was renamed or moved), or there was a build/bundling issue.
 
 When this error occurs, the run fails with a `RUNTIME_ERROR` error code.
 
@@ -21,7 +21,7 @@ if (WorkflowNotRegisteredError.is(error)) { // [!code highlight]
 }
 ```
 
-## API Signature
+## API signature
 
 ### Properties
 
@@ -36,14 +36,14 @@ interface WorkflowNotRegisteredError {
 export default WorkflowNotRegisteredError;`}
 />
 
-### Static Methods
+### Static methods
 
 #### `WorkflowNotRegisteredError.is(value)`
 
-Type-safe check for `WorkflowNotRegisteredError` instances. Preferred over `instanceof` because it works across module boundaries and VM contexts.
+Type-safe check for `WorkflowNotRegisteredError` instances. Preferred over `instanceof` because it works across module boundaries and virtual machine contexts.
 
 <Callout>
-The `.is()` method works in server-side Node.js code (API routes, middleware). When checking the error from `run.returnValue`, use `WorkflowRunFailedError.is()` and inspect `error.cause` — the underlying error is deserialized from the event log.
+The `.is()` method works in server-side Node.js code (API routes, middleware). When checking the error from `run.returnValue`, use `WorkflowRunFailedError.is()` and inspect `error.cause`: the underlying error is deserialized from the event log.
 </Callout>
 
 ```typescript
@@ -54,4 +54,3 @@ if (WorkflowNotRegisteredError.is(error)) {
   // error is typed as WorkflowNotRegisteredError
 }
 ```
-

package/docs/api-reference/workflow-errors/workflow-run-cancelled-error.mdx

@@ -1,17 +1,19 @@
 ---
 title: WorkflowRunCancelledError
-description: Thrown when awaiting the return value of a cancelled workflow run.
+description: Thrown when awaiting the return value of a canceled workflow run.
 type: reference
-summary: Catch WorkflowRunCancelledError when awaiting run.returnValue on a run that was cancelled.
+summary: Catch WorkflowRunCancelledError when awaiting run.returnValue on a run that was canceled.
 related:
   - /docs/api-reference/workflow-errors/workflow-run-failed-error
   - /docs/api-reference/workflow-errors/workflow-run-not-found-error
 ---
 
-`WorkflowRunCancelledError` is thrown when awaiting `run.returnValue` on a workflow run that was explicitly cancelled via `run.cancel()`. Cancelled runs do not produce a return value.
+`WorkflowRunCancelledError` is thrown when awaiting `run.returnValue` on a workflow run that was explicitly canceled via `run.cancel()`. Canceled runs do not produce a return value.
 
 You can check for cancellation before awaiting by inspecting `run.status`.
 
+A canceled run is terminal, so this error is non-retryable (`fatal: true`). Inside a workflow, `await run.returnValue` runs as a step, and that step fails on its first attempt instead of spending its retry budget re-reading a run that cannot change. Errors from *failing to read* the run, such as a transport blip, stay retryable.
+
 ```typescript lineNumbers
 import { WorkflowRunCancelledError } from "workflow/errors"
 declare const run: { status: Promise<string>; returnValue: Promise<any> }; // @setup
@@ -25,22 +27,27 @@ try {
 }
 ```
 
-## API Signature
+## API signature
 
 ### Properties
 
 <TSDoc
 definition={`
 interface WorkflowRunCancelledError {
-  /** The ID of the cancelled run. */
+  /** The ID of the canceled run. */
   runId: string;
+  /**
+   * Always \`true\`. A canceled run is terminal, so a step that reads one is
+   * not retried.
+   */
+  fatal: true;
   /** The error message. */
   message: string;
 }
 export default WorkflowRunCancelledError;`}
 />
 
-### Static Methods
+### Static methods
 
 #### `WorkflowRunCancelledError.is(value)`
 

package/docs/api-reference/workflow-errors/workflow-run-failed-error.mdx

@@ -11,7 +11,9 @@ related:
 
 `WorkflowRunFailedError` is thrown when awaiting `run.returnValue` on a workflow run whose status is `'failed'`. This indicates that the workflow encountered a fatal error during execution and cannot produce a return value.
 
-The `cause` property holds the original thrown value, hydrated through the workflow serialization pipeline so its type identity (e.g. `FatalError`, `RetryableError`, custom `Error` subclasses), `cause` chain, and custom properties are preserved. Because any JavaScript value can be thrown, `cause` is typed as `unknown` — narrow it with `instanceof Error` (or a more specific check) before accessing fields like `message`. The high-level error classification is exposed as the top-level `errorCode` property.
+The `cause` property holds the original thrown value, hydrated through the workflow serialization pipeline so its type identity (e.g. `FatalError`, `RetryableError`, custom `Error` subclasses), `cause` chain, and custom properties are preserved. Because any JavaScript value can be thrown, `cause` is typed as `unknown`, so narrow it with `instanceof Error` (or a more specific check) before accessing fields like `message`. The high-level error classification is exposed as the top-level `errorCode` property.
+
+A failed run is terminal, so this error is non-retryable (`fatal: true`). Inside a workflow, `await run.returnValue` runs as a step, and that step fails on its first attempt instead of spending its retry budget re-reading a run that cannot change: the remote failure reaches the caller immediately, and the caller catches a `WorkflowRunFailedError` rather than a retry-exhaustion wrapper. Errors from *failing to read* the run, such as a transport blip, stay retryable.
 
 ```typescript lineNumbers
 import { WorkflowRunFailedError } from "workflow/errors"
@@ -31,7 +33,7 @@ try {
 }
 ```
 
-## API Signature
+## API signature
 
 ### Properties
 
@@ -45,22 +47,27 @@ interface WorkflowRunFailedError {
    * the workflow serialization pipeline. Preserves the original type identity
    * (Error subclasses, FatalError, custom classes with WORKFLOW_SERIALIZE,
    * etc.) and custom properties. Typed as \`unknown\` because any value can
-   * be thrown — narrow with \`instanceof Error\` before accessing fields.
+   * be thrown, so narrow with \`instanceof Error\` before accessing fields.
    */
   cause: unknown;
   /** The high-level error category (e.g. \`USER_ERROR\`, \`RUNTIME_ERROR\`). */
   errorCode?: string;
+  /**
+   * Always \`true\`. A failed run is terminal, so a step that reads one is not
+   * retried.
+   */
+  fatal: true;
   /** The error message. */
   message: string;
 }
 export default WorkflowRunFailedError;`}
 />
 
-### Static Methods
+### Static methods
 
 #### `WorkflowRunFailedError.is(value)`
 
-Type-safe check for `WorkflowRunFailedError` instances. Preferred over `instanceof` because it works across module boundaries and VM contexts.
+Type-safe check for `WorkflowRunFailedError` instances. Preferred over `instanceof` because it works across module boundaries and virtual machine contexts.
 
 ```typescript
 import { WorkflowRunFailedError } from "workflow/errors"

package/docs/api-reference/workflow-errors/workflow-run-not-completed-error.mdx

@@ -0,0 +1,58 @@
+---
+title: WorkflowRunNotCompletedError
+description: Thrown when requesting the result of a workflow run that has not completed yet.
+type: reference
+summary: Catch WorkflowRunNotCompletedError when reading the return value of a run that is still pending or running.
+related:
+  - /docs/api-reference/workflow-api/get-run
+---
+
+`WorkflowRunNotCompletedError` is thrown when requesting the result of a workflow run that has not completed yet. The run's current status (for example `pending` or `running`) is available on the error.
+
+[`run.returnValue()`](/docs/api-reference/workflow-api/get-run) handles this error internally (it polls until the run completes), so you will mainly encounter it when building custom polling logic on lower-level APIs.
+
+```typescript lineNumbers
+import { WorkflowRunNotCompletedError } from "workflow/errors"
+declare function readRunResult(runId: string): Promise<unknown>; // @setup
+declare const runId: string; // @setup
+
+try {
+  const result = await readRunResult(runId);
+} catch (error) {
+  if (WorkflowRunNotCompletedError.is(error)) { // [!code highlight]
+    console.log(`Run ${error.runId} is still ${error.status}`);
+  }
+}
+```
+
+## API signature
+
+### Properties
+
+<TSDoc
+definition={`
+interface WorkflowRunNotCompletedError {
+  /** The workflow run ID. */
+  runId: string;
+  /** The run's status at the time of the error (e.g. "pending", "running"). */
+  status: string;
+  /** The error message. */
+  message: string;
+}
+export default WorkflowRunNotCompletedError;`}
+/>
+
+### Static methods
+
+#### `WorkflowRunNotCompletedError.is(value)`
+
+Type-safe check for `WorkflowRunNotCompletedError` instances. Preferred over `instanceof` because it works across module boundaries and virtual machine contexts.
+
+```typescript
+import { WorkflowRunNotCompletedError } from "workflow/errors"
+declare const error: unknown; // @setup
+
+if (WorkflowRunNotCompletedError.is(error)) {
+  // error is typed as WorkflowRunNotCompletedError
+}
+```

package/docs/api-reference/workflow-errors/workflow-run-not-found-error.mdx

@@ -10,7 +10,7 @@ related:
 
 `WorkflowRunNotFoundError` is thrown when performing operations on a workflow run that does not exist. This includes calling methods like `run.status`, `run.cancel()`, or awaiting `run.returnValue` on a run whose ID does not match any known workflow run.
 
-Note that `getRun(id)` itself is synchronous and will not throw — the error is raised when subsequent operations on the run object discover the run is missing.
+`getRun(id)` itself is synchronous and will not throw. Subsequent operations on the run object raise the error when they discover the run is missing.
 
 ```typescript lineNumbers
 import { WorkflowRunNotFoundError } from "workflow/errors"
@@ -25,7 +25,7 @@ try {
 }
 ```
 
-## API Signature
+## API signature
 
 ### Properties
 
@@ -40,11 +40,11 @@ interface WorkflowRunNotFoundError {
 export default WorkflowRunNotFoundError;`}
 />
 
-### Static Methods
+### Static methods
 
 #### `WorkflowRunNotFoundError.is(value)`
 
-Type-safe check for `WorkflowRunNotFoundError` instances. Preferred over `instanceof` because it works across module boundaries and VM contexts.
+Type-safe check for `WorkflowRunNotFoundError` instances. Preferred over `instanceof` because it works across module boundaries and virtual machine contexts.
 
 ```typescript
 import { WorkflowRunNotFoundError } from "workflow/errors"

package/docs/api-reference/workflow-errors/workflow-runtime-error.mdx

@@ -0,0 +1,58 @@
+---
+title: WorkflowRuntimeError
+description: Thrown when the workflow runtime encounters an execution error, such as serialization failures or timeouts.
+type: reference
+summary: Catch WorkflowRuntimeError for runtime-level failures like unserializable values or workflow timeouts.
+related:
+  - /docs/foundations/serialization
+  - /docs/foundations/errors-and-retries
+---
+
+`WorkflowRuntimeError` is thrown when the workflow runtime encounters an error executing a workflow. Common causes include:
+
+- Values crossing the workflow/step boundary that cannot be serialized
+- Workflow execution timeouts
+- Invalid runtime state, such as misconfigured streams
+
+```typescript lineNumbers
+import { WorkflowRuntimeError } from "workflow/errors"
+declare function runWorkflowOperation(): Promise<void>; // @setup
+
+try {
+  await runWorkflowOperation();
+} catch (error) {
+  if (WorkflowRuntimeError.is(error)) { // [!code highlight]
+    console.error("Workflow runtime error:", error.message);
+  }
+}
+```
+
+## API signature
+
+### Properties
+
+<TSDoc
+definition={`
+interface WorkflowRuntimeError {
+  /** The error message. */
+  message: string;
+  /** The underlying cause, when provided. */
+  cause?: unknown;
+}
+export default WorkflowRuntimeError;`}
+/>
+
+### Static methods
+
+#### `WorkflowRuntimeError.is(value)`
+
+Type-safe check for `WorkflowRuntimeError` instances. Preferred over `instanceof` because it works across module boundaries and VM contexts.
+
+```typescript
+import { WorkflowRuntimeError } from "workflow/errors"
+declare const error: unknown; // @setup
+
+if (WorkflowRuntimeError.is(error)) {
+  // error is typed as WorkflowRuntimeError
+}
+```

package/docs/api-reference/workflow-errors/workflow-world-error.mdx

@@ -12,7 +12,7 @@ related:
 
 `WorkflowWorldError` is the base error class for failures originating from a workflow world (storage backend). World implementations (local, Postgres, Vercel) throw subclasses of this error when storage operations fail.
 
-You can use `instanceof WorkflowWorldError` to catch any world-related error regardless of the specific type. Note that the static `.is()` method only matches errors constructed directly as `WorkflowWorldError` — use the subclass-specific `.is()` methods (e.g. `EntityConflictError.is()`) to match specific error types.
+You can use `instanceof WorkflowWorldError` to catch any World-related error regardless of the specific type. The static `.is()` method only matches errors constructed directly as `WorkflowWorldError`. Use the subclass-specific `.is()` methods (for example, `EntityConflictError.is()`) to match specific error types.
 
 <Callout>
 Most world errors are handled automatically by the Workflow runtime. You will typically only encounter these errors when interacting with world storage APIs directly or when there are infrastructure-level issues.
@@ -33,7 +33,7 @@ try {
 }
 ```
 
-## API Signature
+## API signature
 
 ### Properties
 
@@ -54,11 +54,11 @@ interface WorkflowWorldError {
 export default WorkflowWorldError;`}
 />
 
-### Static Methods
+### Static methods
 
 #### `WorkflowWorldError.is(value)`
 
-Type-safe check that matches only errors constructed directly as `WorkflowWorldError`. Does not match subclasses like `EntityConflictError` — use `instanceof` to catch all world errors, or the subclass-specific `.is()` methods.
+Type-safe check that matches only errors constructed directly as `WorkflowWorldError`. Does not match subclasses like `EntityConflictError`. Use `instanceof` to catch all world errors, or the subclass-specific `.is()` methods.
 
 ```typescript
 import { WorkflowWorldError } from "workflow/errors"
@@ -73,7 +73,7 @@ if (WorkflowWorldError.is(error)) {
 
 The following error types extend `WorkflowWorldError`:
 
-- [`EntityConflictError`](/docs/api-reference/workflow-errors/entity-conflict-error) — operation conflicts with entity state
-- [`RunExpiredError`](/docs/api-reference/workflow-errors/run-expired-error) — run has expired
-- [`TooEarlyError`](/docs/api-reference/workflow-errors/too-early-error) — request made before system is ready
-- [`ThrottleError`](/docs/api-reference/workflow-errors/throttle-error) — request was rate-limited
+- [`EntityConflictError`](/docs/api-reference/workflow-errors/entity-conflict-error): operation conflicts with entity state
+- [`RunExpiredError`](/docs/api-reference/workflow-errors/run-expired-error): run has expired
+- [`TooEarlyError`](/docs/api-reference/workflow-errors/too-early-error): request made before system is ready
+- [`ThrottleError`](/docs/api-reference/workflow-errors/throttle-error): request was rate-limited

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

@@ -22,29 +22,34 @@ These APIs are available but are **seeded or fixed** to ensure deterministic beh
 
 | API | Behavior |
 |-----|----------|
-| [`Math.random()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/random) | Seeded random number generator — same seed produces the same sequence every replay |
-| [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) / `Date.now()` / `new Date()` | Returns a fixed timestamp that advances with the workflow's logical clock |
-| [`crypto.getRandomValues()`](https://developer.mozilla.org/en-US/docs/Web/API/Crypto/getRandomValues) | Seeded — produces deterministic output for a given workflow run |
-| [`crypto.randomUUID()`](https://developer.mozilla.org/en-US/docs/Web/API/Crypto/randomUUID) | Seeded — produces deterministic UUIDs for a given workflow run |
-| [`crypto.subtle.digest()`](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/digest) | Passes through to the real implementation (SHA-256, etc. are deterministic by nature) |
+| [`Math.random()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/random) | Seeded random number generator: same seed produces the same sequence every replay |
+| [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) / `Date.now()` / `new Date()` | Returns the workflow's logical clock: the run's creation time until the first step result, hook payload, hook registration, wait completion or abort reaches the workflow, then the time that event was recorded, advancing as each later one is delivered. Identical on every replay of the same log |
+| [`crypto.getRandomValues()`](https://developer.mozilla.org/en-US/docs/Web/API/Crypto/getRandomValues) | Seeded: produces deterministic output for a given workflow run |
+| [`crypto.randomUUID()`](https://developer.mozilla.org/en-US/docs/Web/API/Crypto/randomUUID) | Seeded: produces deterministic UUIDs for a given workflow run |
+| [`crypto.subtle.digest()`](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/digest) | Computed synchronously via `node:crypto` (values are byte-identical to WebCrypto), so the promise settles at a deterministic point during replay |
 
 <Callout type="info">
 You can safely use `Math.random()`, `Date.now()`, and `crypto.randomUUID()` in workflow functions. The framework ensures these return the same values across replays.
 </Callout>
 
-## Web Platform APIs
+<Callout type="warn">
+`Math.random()`, `crypto.randomUUID()`, and `crypto.getRandomValues()` are derived from the run's seed rather than a secret, so their values are predictable to anyone who knows that seed. Don't use them for secrets, one-time codes, or tokens that must be unguessable; generate those in a step instead. See [Hook and webhook security](/docs/foundations/hooks#security).
+</Callout>
+
+## Web platform APIs
 
 These standard Web APIs are available in workflow functions:
 
 - [`Headers`](https://developer.mozilla.org/en-US/docs/Web/API/Headers)
 - [`TextEncoder`](https://developer.mozilla.org/en-US/docs/Web/API/TextEncoder) / [`TextDecoder`](https://developer.mozilla.org/en-US/docs/Web/API/TextDecoder)
 - [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL) / [`URLSearchParams`](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams)
-- [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request) / [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response) — custom implementations with [special behavior in the workflow context](/docs/foundations/serialization#request--response). Body methods like `.json()` and `.text()` are automatically treated as step invocations.
+- [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request) / [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response): custom implementations with [special behavior in the workflow context](/docs/foundations/serialization#request--response). Body methods like `.json()` and `.text()` are automatically treated as step invocations.
 - [`console`](https://developer.mozilla.org/en-US/docs/Web/API/console)
 - [`structuredClone`](https://developer.mozilla.org/en-US/docs/Web/API/Window/structuredClone)
 - [`atob`](https://developer.mozilla.org/en-US/docs/Web/API/Window/atob) / [`btoa`](https://developer.mozilla.org/en-US/docs/Web/API/Window/btoa)
+- [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController) / [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal): A durable, serializable implementation whose abort state survives replay and can be passed into steps to cancel in-flight work. See [Cancellation](/docs/foundations/cancellation).
 
-## Environment Variables
+## Environment variables
 
 `process.env` is available as a **read-only, frozen** snapshot of the environment variables at the time the workflow was started. You cannot modify it.
 
@@ -53,11 +58,11 @@ export async function myWorkflow() {
   "use workflow";
 
   const apiKey = process.env.API_KEY; // works
-  process.env.FOO = "bar"; // throws — process.env is frozen
+  process.env.FOO = "bar"; // throws: process.env is frozen
 }
 ```
 
-## Binary Data
+## Binary data
 
 Standard JavaScript typed arrays (`Uint8Array`, `Int32Array`, `Float64Array`, etc.) are available in workflow functions.
 
@@ -92,7 +97,7 @@ target.setFromHex("48656c6c6f"); // { read: 10, written: 5 }
 These methods are polyfilled in the workflow environment. When the JavaScript runtime ships native support, the polyfill is automatically bypassed.
 </Callout>
 
-## Not Available
+## Not available
 
 The following are **not available** in workflow functions. Move this logic to [step functions](/docs/foundations/workflows-and-steps#step-functions) instead.
 
@@ -100,3 +105,6 @@ The following are **not available** in workflow functions. Move this logic to [s
 - **Global `fetch`**: Use [`import { fetch } from "workflow"`](/docs/api-reference/workflow/fetch) instead. See [fetch-in-workflow](/docs/errors/fetch-in-workflow).
 - **Timers**: `setTimeout`, `setInterval`, `setImmediate`, and their `clear*` counterparts. Use [`sleep()`](/docs/api-reference/workflow/sleep) instead. See [timeout-in-workflow](/docs/errors/timeout-in-workflow).
 - **`Buffer`**: Node.js-specific API. Use `Uint8Array` with `toBase64()` / `fromBase64()` / `toHex()` / `fromHex()` for binary data encoding, or `atob()` / `btoa()` for string-based base64.
+- **`WeakRef` and `FinalizationRegistry`**: Garbage collection timing is not deterministic, so observing it would make workflow code impossible to replay. (`WeakMap` and `WeakSet` remain available since they do not expose garbage collection state.)
+- **`Atomics.waitAsync`**: a wall-clock timer, which cannot be replayed. Use [`sleep()`](/docs/api-reference/workflow/sleep) instead.
+- **Async `WebAssembly` compilation**: The `compile`, `instantiate`, `compileStreaming`, and `instantiateStreaming` methods resolve on compile-thread timing. The synchronous `new WebAssembly.Module()` and `new WebAssembly.Instance()` constructors remain available.