Self-hosted custom worlds can silently use an incompatible Workflow SDK major

[ruiconti]

eve version

eve@0.13.3

Node.js version

Not recorded. This is a dependency-resolution and runtime compatibility failure.

Where does the bug occur?

Self-hosted deployment with a configured Workflow world, including eve build && eve start.

Describe the bug

The custom-world docs use @workflow/world-postgres and tell readers to install it, but provide no compatible version or installation command. The 0.13.3 docs show the package name and say only to install it.

At the time of filing, the registry latest for @workflow/world-postgres is 4.2.0; its dependency tree uses @workflow/world@4.2.0. eve@0.13.3 bundles @workflow/core@5.0.0-beta.19 internally (package source, vendor definition).

The configuration accepts any nonempty package name, and the world bootstrap checks only that the factory returns a World-shaped value (config validation, world bootstrap). There is no compatibility check between the selected world and eve's bundled SDK.

Observed behavior: installation and startup succeed. The first real workflow run later fails with a deep ZodError, which gives no useful clue that the process has mixed Workflow SDK major versions.

Steps to reproduce

1. Create a self-hosted eve app on eve@0.13.3.
2. Run pnpm add @workflow/world-postgres without a version.
3. Set experimental.workflow.world to @workflow/world-postgres.
4. Build, start, and send a request that runs a workflow.

Expected behavior

The documented install path selects a compatible world version, or eve rejects an incompatible world before any user work runs. The error should name the expected and discovered Workflow SDK versions.

Actual behavior

The default install picks a 4.x world next to eve's bundled 5.x beta SDK. The incompatibility surfaces later as an unrelated-looking ZodError during workflow execution.

Suggested fix

• Document the supported world package version alongside each self-hosting example.
• Add an install-time or startup compatibility check for configured worlds, with an actionable error that names the selected package and required SDK major.