Self-hosted Workflow worlds require undocumented WORKFLOW_QUEUE_NAMESPACE=eve

[ruiconti]

eve version

eve@0.13.3

Node.js version

Not recorded.

Where does the bug occur?

A self-hosted app with a configured queue-backed Workflow world.

Describe the bug

eve compiles its workflow entrypoint with the fixed eve namespace. The namespace constants produce the __eve_wkf_workflow_ queue prefix, and the generated entrypoint passes namespace: "eve" to workflowEntrypoint.

The Vercel output path explicitly injects WORKFLOW_QUEUE_NAMESPACE=eve into generated workflow functions (source). The self-host docs do not name that variable. They only say that the world should read host-specific options from runtime environment variables (docs).

This is timing-sensitive as well: the configured world factory starts before eve applies the queue namespace during start or deliver (world bootstrap, runtime assignment).

Observed behavior: with a self-selected world and no WORKFLOW_QUEUE_NAMESPACE, queue dispatch fails with HTTP 400 Unhandled queue. Setting WORKFLOW_QUEUE_NAMESPACE=eve makes the world use the handler prefix eve registered.

Steps to reproduce

1. Configure a queue-backed world in experimental.workflow.world.
2. Configure its required database and queue credentials, but do not set WORKFLOW_QUEUE_NAMESPACE.
3. Run the self-hosted app and send a turn.
4. Observe Unhandled queue from the world.
5. Set WORKFLOW_QUEUE_NAMESPACE=eve before starting the process and repeat.

Expected behavior

Selecting a world through eve config should make the queue namespace agree with the handler namespace automatically. If that cannot be done safely, the self-host docs and the runtime error should state the required value.

Actual behavior

The required namespace is implicit in generated code and Vercel-only environment setup. The self-host error does not identify the namespace mismatch.

Suggested fix

• Apply WORKFLOW_QUEUE_NAMESPACE=eve before creating a configured world, unless the user explicitly supplies an intentional override.
• Document the variable and its required value in every custom-world self-hosting example.
• Include the configured and expected namespace in the unhandled-queue error.