@workflow/errors

Major Changes

• breaking

  Initial v5 beta release

• breaking

  Run and step errors are now serialized through the workflow serialization pipeline, preserving original class identity and cause chains on WorkflowRunFailedError.cause. Pre-upgrade failed runs in the world-postgres legacy error text column surface as error: undefined on read; the original payload is still readable directly from the errorJson column for manual inspection.

Minor Changes

• Validate world.analytics arguments up front: an invalid id, an out-of-range page limit, an oversized attribute filter, or a half-open startTime/endTime window now throws a WorkflowWorldError with code: 'INVALID_ARGUMENT' and field set to the offending parameter, instead of failing the request. The message names the method, the parameter, and what it received. Adds ANALYTICS_RUN_SCOPED_PAGE_LIMIT, ANALYTICS_PAGE_LIMIT and ANALYTICS_MAX_ATTRIBUTE_FILTERS.

  Deprecate analytics.events.listByCorrelationId() in favour of analytics.events.list({ runId, correlationId }).

  Fix analytics.attributes.list() timestamps being shifted by the local UTC offset.

• Strengthen the event-creation precondition guard: replay-context writes now also send the number of loaded events, so a snapshot that is missing an event is rejected instead of committing a divergent event log, and a rejection restarts the replay in-process (consuming the events a world may attach to the rejection) rather than re-committing the rejected payload or re-invoking over the queue. @workflow/world-local and @workflow/world-postgres do not implement the check.

• Add an opt-in optimistic-concurrency guard for event creation (WORKFLOW_PRECONDITION_GUARD=1): replay-context event creations send a stateUpdatedAt snapshot timestamp, and the runtime reloads the event log and retries (then falls back to a queue re-invocation) when the backend reports a newer out-of-band event with a 412 PreconditionFailedError.

• Re-route a queue delivery that reaches a deployment other than the one its run is pinned to, retry transient publishing failures through normal queue redelivery, and fail the run with the new DEPLOYMENT_MISMATCH error code once the recovery budget is spent.

• Add createHook({ experimental_force: true }) option, which takes a hook token over from the run that currently holds it instead of rejecting with HookConflictError. Previous runs awaiting the hook are rejected with HookForceClaimedError naming the run that took the token. See experimental_force docs for details.

• Add an experimental_retention option to start(): experimental_retention: 0 asks the World to delete the run's user data as soon as the run completes or fails, while keeping the run itself listable. Implemented on the Vercel, Postgres and Local Worlds. Reading a run whose data has expired now throws RunExpiredError instead of resolving to a placeholder.

• Add an optional invoke method and capability to the World interface. It routes a payload to the runner handling the specified runId and returns a promise for its response. In world-postgres, this uses a regular queue roundtrip with a run-scoped queue. The runtime uses invoke when available, initially to resume hooks.

• Add a catchable StreamError and classify Workflow stream infrastructure failures as STREAM_ERROR instead of USER_ERROR.

Patch Changes

• Expose the active run ID on hook token conflict errors.

• Report corrupted event logs with a distinct CorruptedEventLogError type and CORRUPTED_EVENT_LOG run error code.

• Replace the chalk import in @workflow/errors/ansi with a tiny inline ANSI shim. @workflow/errors/ansi is reachable from the workflow-VM bundle (via @workflow/core/workflow → context-errors → context-violation-error → here), and chalk pulls in supports-color, which calls require('os') at module load — crashing every workflow with ReferenceError: require is not defined in the sandboxed VM.

• Enforce a server-supplied per-run event limit (default 25K)

• Embed source content in published sourcemaps.

• Friendlier workflow error messages. New SerializationError, WorkflowBuildError, and structured context-violation classes (e.g. NotInWorkflowContextError) with actionable hints and docs links applied to user-facing throw sites; FatalError.is() recognizes any error with fatal: true so context violations and serialization failures now fail fast instead of burning retry attempts. Runtime logs are namespaced under [workflow-sdk] and gain errorAttribution (user vs sdk) plus class-aware hints

• The WORKFLOW_PRECONDITION_GUARD event-creation guard is now on by default; opt out with WORKFLOW_PRECONDITION_GUARD=0.

• Replace util.inspect's default object dump for runtime structured-log metadata with an opinionated, workflow-aware formatter. The runtime logger uses color-coded metadata blocks.

• Rename useworkflow.dev URLs to workflow-sdk.dev

• Retry transient workflow replay divergence before classifying repeated divergence as a corrupted event log.

• Remove the retired step route runtime and make queue health checks target the combined flow handler.

• Classify SDK-level AES-GCM encryption failures as RUNTIME_ERROR instead of USER_ERROR via a new RuntimeDecryptionError.

• Record fatal world response contract failures as non-retryable workflow errors.

• Replay-context event writes now always report the log position they replayed from, and the WORKFLOW_PRECONDITION_GUARD flag is removed.

• Surface typed terminal errors when stream retention expires.

• Mark WorkflowRunFailedError and WorkflowRunCancelledError as non-retryable, so a step that reads a terminal run's returnValue fails on its first attempt with the error intact instead of exhausting its retry budget first.

• Use inline sourcemaps for all workspace packages; published packages no longer ship external .js.map files.