Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

fix(eve): self-hosted workflow queue handler + world version-compat guard (#308)

Pranay Prakashe5ccf933e766
diff --git a/.changeset/self-host-workflow-runtime.md b/.changeset/self-host-workflow-runtime.md
new file mode 100644
index 000000000..bc3dbcf3a
--- /dev/null
+++ b/.changeset/self-host-workflow-runtime.md
@@ -0,0 +1,5 @@
+---
+"eve": patch
+---
+
+Self-hosted `eve start` now registers the workflow queue handler for custom (non-Vercel) worlds, so jobs dispatched by a configured world no longer return `Unhandled queue` or leave runs stuck `pending` — and you no longer need `eve dev --no-ui` to run a local world in production. eve also fails fast at boot with an actionable error when a configured workflow world's `@workflow/*` version is incompatible with the line eve bundles, instead of surfacing a cryptic `ZodError` deep in workflow replay.
diff --git a/packages/eve/src/internal/application/compiled-artifacts.test.ts b/packages/eve/src/internal/application/compiled-artifacts.test.ts
index 3c0ecf0d9..ca4968ca6 100644
--- a/packages/eve/src/internal/application/compiled-artifacts.test.ts
+++ b/packages/eve/src/internal/application/compiled-artifacts.test.ts
@@ -59,7 +59,7 @@ describe("createCompiledArtifactsBootstrapSource", () => {
expect(source).toContain('import * as workflowWorldModule from "@acme/eve-world";');
expect(source).toContain(
- "await installConfiguredWorkflowWorld({ module: workflowWorldModule });",
+ 'await installConfiguredWorkflowWorld({ module: workflowWorldModule, packageName: "@acme/eve-world" });',
);
});
});
diff --git a/packages/eve/src/internal/application/compiled-artifacts.ts b/packages/eve/src/internal/application/compiled-artifacts.ts
index 3883433db..e3bd0f966 100644
--- a/packages/eve/src/internal/application/compiled-artifacts.ts
+++ b/packages/eve/src/internal/application/compiled-artifacts.ts
@@ -174,7 +174,10 @@ function createWorkflowWorldBootstrapBody(
return [];
}
- return ["", "await installConfiguredWorkflowWorld({ module: workflowWorldModule });"];
+ return [
+ "",
+ `await installConfiguredWorkflowWorld({ module: workflowWorldModule, packageName: ${JSON.stringify(world)} });`,
+ ];
}
function createInstrumentationPluginSource(input: {
diff --git a/packages/eve/src/internal/application/package.test.ts b/packages/eve/src/internal/application/package.test.ts
index 747b4b322..137665b5f 100644
--- a/packages/eve/src/internal/application/package.test.ts
+++ b/packages/eve/src/internal/application/package.test.ts
@@ -1,6 +1,9 @@
import { describe, expect, it } from "vitest";
-import { resolveWorkflowModulePath } from "#internal/application/package.js";
+import {
+ resolveExpectedWorkflowVersion,
+ resolveWorkflowModulePath,
+} from "#internal/application/package.js";
describe("resolveWorkflowModulePath", () => {
it("resolves historical workflow specifiers to narrowed runtime modules", () => {
@@ -19,3 +22,11 @@ describe("resolveWorkflowModulePath", () => {
);
});
});
+
+describe("resolveExpectedWorkflowVersion", () => {
+ it("reads the @workflow/core line from eve's own package.json", () => {
+ // Single source of truth: eve declares the workflow line it bundles in its
+ // own package.json, so this resolves to a concrete prerelease version.
+ expect(resolveExpectedWorkflowVersion()).toMatch(/^\d+\.\d+\.\d+/);
+ });
+});
diff --git a/packages/eve/src/internal/application/package.ts b/packages/eve/src/internal/application/package.ts
index c245e00bc..adf1bd81d 100644
--- a/packages/eve/src/internal/application/package.ts
+++ b/packages/eve/src/internal/application/package.ts
@@ -249,6 +249,63 @@ export function resolveInstalledPackageInfo(): InstalledPackageInfo {
return cachedPackageInfo;
}
+const EXPECTED_WORKFLOW_VERSION_PACKAGE = "@workflow/core";
+
+function readWorkflowVersionFromManifest(value: unknown): string | undefined {
+ const manifest = value as {
+ dependencies?: Record<string, unknown>;
+ devDependencies?: Record<string, unknown>;
+ peerDependencies?: Record<string, unknown>;
+ };
+
+ for (const section of [
+ manifest.devDependencies,
+ manifest.dependencies,
+ manifest.peerDependencies,
+ ]) {
+ const declared = section?.[EXPECTED_WORKFLOW_VERSION_PACKAGE];
+
+ if (typeof declared === "string" && declared.trim().length > 0) {
+ return declared;
+ }
+ }
+
+ return undefined;
+}
+
+/**
+ * Resolves the `@workflow/core` version this eve release bundles, read from
+ * eve's own `package.json`.
+ *
+ * This is the single source of truth for the `@workflow/*` line eve targets, so
+ * compatibility checks (see `assertWorkflowWorldCompatibility`) never hardcode a
+ * version. eve's `package.json` is published with its `devDependencies` intact
+ * even though those packages are vendored, so the entry is readable from an
+ * installed eve as well as a source checkout. Returns `undefined` when the
+ * entry cannot be read so callers can no-op rather than fail.
+ */
+export function resolveExpectedWorkflowVersion(): string | undefined {
+ const packageRoot = tryResolvePackageRoot();
+
+ if (packageRoot !== undefined) {
+ try {
+ return readWorkflowVersionFromManifest(
+ JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8")),
+ );
+ } catch {
+ // Fall through to module-resolution lookup below.
+ }
+ }
+
+ try {
+ return readWorkflowVersionFromManifest(
+ JSON.parse(readFileSync(require.resolve(`${EVE_PACKAGE_NAME}/package.json`), "utf8")),
+ );
+ } catch {
+ return undefined;
+ }
+}
+
/**
* Resolves a Workflow runtime module from eve's narrowed Workflow dependencies.
*
diff --git a/packages/eve/src/internal/application/paths.ts b/packages/eve/src/internal/application/paths.ts
index fc55d89f7..924acb0f4 100644
--- a/packages/eve/src/internal/application/paths.ts
+++ b/packages/eve/src/internal/application/paths.ts
@@ -29,7 +29,12 @@ function getWorkflowBuildCacheKey(appRoot: string): string {
return createHash("sha256").update(appRoot).digest("hex").slice(0, 12);
}
-function isVercelBuildEnvironment(): boolean {
+/**
+ * Reports whether the current process is running inside a Vercel build or
+ * deployment. Vercel sets `VERCEL` in both build and runtime environments, so
+ * this is the canonical signal for "managed by Vercel" versus self-hosted.
+ */
+export function isVercelBuildEnvironment(): boolean {
return Boolean(process.env.VERCEL);
}
diff --git a/packages/eve/src/internal/nitro/host/configure-nitro-routes.test.ts b/packages/eve/src/internal/nitro/host/configure-nitro-routes.test.ts
index 9b0607d3b..ff3e3b478 100644
--- a/packages/eve/src/internal/nitro/host/configure-nitro-routes.test.ts
+++ b/packages/eve/src/internal/nitro/host/configure-nitro-routes.test.ts
@@ -24,7 +24,9 @@ interface PreparedApplicationHostStub {
compileResult: {
manifest: {
channels: [];
- config: Record<string, never>;
+ config: {
+ experimental?: { workflow?: { world?: string } };
+ };
};
project: {
agentRoot: string;
@@ -73,6 +75,13 @@ vi.mock("../../workflow-bundle/builder.js", () => ({
},
}));
+// Mock paths.js so the unit test avoids its heavyweight workflow-runtime import
+// graph while preserving the real, env-driven `isVercelBuildEnvironment`
+// semantics that the direct-handler gate depends on.
+vi.mock("../../application/paths.js", () => ({
+ isVercelBuildEnvironment: () => Boolean(process.env.VERCEL),
+}));
+
const { configureNitroRoutes } = await import("./configure-nitro-routes.js");
const { EVE_HEALTH_ROUTE_PATH, EVE_INFO_ROUTE_PATH } = await import("#protocol/routes.js");
@@ -99,7 +108,7 @@ function createNitroStub(
}
function createPreparedHost(
- input: { appRoot?: string; workflowBuildDir?: string } = {},
+ input: { appRoot?: string; workflowWorld?: string; workflowBuildDir?: string } = {},
): PreparedApplicationHost {
const appRoot = input.appRoot ?? "G:\\projects\\test-eve";
@@ -108,7 +117,10 @@ function createPreparedHost(
compileResult: {
manifest: {
channels: [],
- config: {},
+ config:
+ input.workflowWorld === undefined
+ ? {}
+ : { experimental: { workflow: { world: input.workflowWorld } } },
},
project: {
agentRoot: `${appRoot}\\agent`,
@@ -132,6 +144,9 @@ describe("configureNitroRoutes", () => {
fsMocks.mkdir.mockClear();
fsMocks.writeFile.mockClear();
workflowBuilderMocks.build.mockClear();
+ // The direct-handler gate keys off `process.env.VERCEL`; ensure each test
+ // starts from a clean, self-hosted (non-Vercel) baseline.
+ vi.unstubAllEnvs();
});
it("registers package-owned route files through file-url virtual handlers", async () => {
@@ -273,15 +288,25 @@ describe("configureNitroRoutes", () => {
);
});
- it("does not register direct workflow queue handlers in production builds", async () => {
- const root = "/tmp/eve-nitro-direct-handlers-prod";
+ it("does not register direct workflow queue handlers for Vercel production builds", async () => {
+ vi.stubEnv("VERCEL", "1");
+
+ const root = "/tmp/eve-nitro-direct-handlers-vercel";
const buildDir = `${root}/nitro`;
const workflowBuildDir = `${root}/workflow-cache`;
const nitro = createNitroStub({ buildDir, dev: false, rootDir: root });
- await configureNitroRoutes(nitro, createPreparedHost({ appRoot: root, workflowBuildDir }), {
- surface: "all",
- });
+ await configureNitroRoutes(
+ nitro,
+ createPreparedHost({
+ appRoot: root,
+ workflowBuildDir,
+ workflowWorld: "@workflow/world-postgres",
+ }),
+ {
+ surface: "all",
+ },
+ );
const workflowHandlerSource = readWriteFileSourceMatching("/workflow/workflows-handler.mjs");
@@ -292,6 +317,54 @@ describe("configureNitroRoutes", () => {
expect(workflowHandlerSource).not.toContain("__eveGetWorkflowWorld");
expect(readWriteFileSourceMatching("/workflow/steps-handler.mjs")).toBeUndefined();
});
+
+ it("registers direct workflow queue handlers for self-hosted production builds with a configured world", async () => {
+ const root = "/tmp/eve-nitro-direct-handlers-self-hosted";
+ const buildDir = `${root}/nitro`;
+ const workflowBuildDir = `${root}/workflow-cache`;
+ const nitro = createNitroStub({ buildDir, dev: false, rootDir: root });
+
+ await configureNitroRoutes(
+ nitro,
+ createPreparedHost({
+ appRoot: root,
+ workflowBuildDir,
+ workflowWorld: "@workflow/world-postgres",
+ }),
+ {
+ surface: "all",
+ },
+ );
+
+ const workflowHandlerSource = readWriteFileSourceMatching("/workflow/workflows-handler.mjs");
+
+ expect(workflowHandlerSource).toContain(
+ 'import { POST } from "../../workflow-cache/workflows.mjs";',
+ );
+ expect(workflowHandlerSource).toContain(
+ "const __eveWorkflowWorld = await __eveGetWorkflowWorld();",
+ );
+ expect(workflowHandlerSource).toContain(
+ '__eveWorkflowWorld.registerHandler("__eve_wkf_workflow_", POST);',
+ );
+ expect(readWriteFileSourceMatching("/workflow/steps-handler.mjs")).toBeUndefined();
+ });
+
+ it("does not register direct workflow queue handlers for self-hosted production builds without a configured world", async () => {
+ const root = "/tmp/eve-nitro-direct-handlers-self-hosted-no-world";
+ const buildDir = `${root}/nitro`;
+ const workflowBuildDir = `${root}/workflow-cache`;
+ const nitro = createNitroStub({ buildDir, dev: false, rootDir: root });
+
+ await configureNitroRoutes(nitro, createPreparedHost({ appRoot: root, workflowBuildDir }), {
+ surface: "all",
+ });
+
+ const workflowHandlerSource = readWriteFileSourceMatching("/workflow/workflows-handler.mjs");
+
+ expect(workflowHandlerSource).not.toContain("registerHandler");
+ expect(workflowHandlerSource).not.toContain("__eveGetWorkflowWorld");
+ });
});
function readWriteFileSourceMatching(suffix: string): string | undefined {
diff --git a/packages/eve/src/internal/nitro/host/configure-nitro-routes.ts b/packages/eve/src/internal/nitro/host/configure-nitro-routes.ts
index 68f8fcb95..3c9a4f017 100644
--- a/packages/eve/src/internal/nitro/host/configure-nitro-routes.ts
+++ b/packages/eve/src/internal/nitro/host/configure-nitro-routes.ts
@@ -13,6 +13,7 @@ import {
normalizeEsmImportSpecifier,
stringifyEsmImportSpecifier,
} from "#internal/application/import-specifier.js";
+import { isVercelBuildEnvironment } from "#internal/application/paths.js";
import {
resolvePackageRoot,
resolvePackageSourceFilePath,
@@ -397,11 +398,23 @@ export async function configureNitroRoutes(
: join(preparedHost.workflowBuildDir, "workflows.mjs")
: undefined;
- // Direct handler registration is dev-only: it only helps when the local
- // workflow queue runs inside the same Nitro dev worker. Production
- // deployments dispatch through Vercel's queue trigger.
+ // Register the direct queue→bundle binding whenever the local/configured
+ // world drives the queue itself, which is true in `eve dev` AND in
+ // self-hosted (non-Vercel) production. In both cases the world dispatches
+ // each job to the matching POST handler in-process, bypassing HTTP loopback
+ // (see `@workflow/world-local`'s queue dispatch: a registered direct handler
+ // short-circuits the `WORKFLOW_LOCAL_BASE_URL` fetch path). Vercel-managed
+ // deploys instead dispatch through Vercel's queue trigger, which calls the
+ // flow route over HTTP, so we never register the binding there — gating on
+ // "not a Vercel build" preserves that path exactly. We additionally require a
+ // configured custom world: without one there is no local world to bind to in
+ // production, so a binding would be dead weight.
+ const hasConfiguredWorkflowWorld =
+ preparedHost.compileResult.manifest.config.experimental?.workflow?.world !== undefined;
+ const localWorldDrivesQueue =
+ nitro.options.dev || (!isVercelBuildEnvironment() && hasConfiguredWorkflowWorld);
const directHandlerEntries: WorkflowDirectHandlerEntry[] =
- nitro.options.dev && workflowBundlePath !== undefined
+ localWorldDrivesQueue && workflowBundlePath !== undefined
? [{ bundlePath: workflowBundlePath, queuePrefix: EVE_WORKFLOW_QUEUE_PREFIX }]
: [];
// Generated handlers will JSON-stringify this at write-time, so we hand them
diff --git a/packages/eve/src/internal/workflow/configure-world.ts b/packages/eve/src/internal/workflow/configure-world.ts
index 1b9fc7680..19ff173a2 100644
--- a/packages/eve/src/internal/workflow/configure-world.ts
+++ b/packages/eve/src/internal/workflow/configure-world.ts
@@ -1,5 +1,13 @@
+import { createRequire } from "node:module";
+import { readFileSync } from "node:fs";
+
import type { World } from "#compiled/@workflow/world/index.js";
+import { resolveExpectedWorkflowVersion } from "#internal/application/package.js";
import { setWorld } from "#internal/workflow/runtime.js";
+import {
+ assertWorkflowWorldCompatibility,
+ type WorkflowWorldManifest,
+} from "#internal/workflow/world-compatibility.js";
export interface ConfiguredWorkflowWorldModule {
readonly [name: string]: unknown;
@@ -8,6 +16,12 @@ export interface ConfiguredWorkflowWorldModule {
export interface InstallConfiguredWorkflowWorldInput {
readonly module: ConfiguredWorkflowWorldModule | (() => unknown);
+ /**
+ * Package name of the configured world (e.g. `@workflow/world-postgres`),
+ * derived from the agent manifest's `experimental.workflow.world`. Used to
+ * resolve the world's `package.json` for the boot-time compatibility check.
+ */
+ readonly packageName?: string;
}
/**
@@ -16,12 +30,46 @@ export interface InstallConfiguredWorkflowWorldInput {
export async function installConfiguredWorkflowWorld(
input: InstallConfiguredWorkflowWorldInput,
): Promise<World> {
+ assertConfiguredWorldCompatibility(input.packageName);
const world = await createWorkflowWorld(input);
setWorld(world);
await world.start?.();
return world;
}
+/**
+ * Fails fast at boot when the configured world's declared `@workflow/*` line is
+ * incompatible with the line this eve release bundles. Best-effort: any failure
+ * to resolve or read the world's `package.json` is swallowed so we never turn a
+ * readable-but-unverifiable setup into a boot failure.
+ */
+function assertConfiguredWorldCompatibility(packageName: string | undefined): void {
+ if (packageName === undefined) {
+ return;
+ }
+
+ const expectedWorkflowVersion = resolveExpectedWorkflowVersion();
+
+ if (expectedWorkflowVersion === undefined) {
+ return;
+ }
+
+ let worldManifest: WorkflowWorldManifest;
+ try {
+ const require = createRequire(import.meta.url);
+ const manifestPath = require.resolve(`${packageName}/package.json`);
+ worldManifest = JSON.parse(readFileSync(manifestPath, "utf8")) as WorkflowWorldManifest;
+ } catch {
+ return;
+ }
+
+ assertWorkflowWorldCompatibility({
+ expectedWorkflowVersion,
+ worldManifest,
+ worldPackageName: packageName,
+ });
+}
+
async function createWorkflowWorld(input: InstallConfiguredWorkflowWorldInput): Promise<World> {
const factory = resolveWorkflowWorldFactory(input);
const world = await factory();
diff --git a/packages/eve/src/internal/workflow/world-compatibility.test.ts b/packages/eve/src/internal/workflow/world-compatibility.test.ts
new file mode 100644
index 000000000..68779a012
--- /dev/null
+++ b/packages/eve/src/internal/workflow/world-compatibility.test.ts
@@ -0,0 +1,105 @@
+import { describe, expect, it } from "vitest";
+
+import { assertWorkflowWorldCompatibility } from "./world-compatibility.js";
+
+const EXPECTED = "5.0.0-beta.24";
+
+describe("assertWorkflowWorldCompatibility", () => {
+ it("throws an actionable error when the world targets an older major line", () => {
+ expect(() =>
+ assertWorkflowWorldCompatibility({
+ worldPackageName: "@workflow/world-postgres",
+ worldManifest: { dependencies: { "@workflow/core": "^4.2.0" } },
+ expectedWorkflowVersion: EXPECTED,
+ }),
+ ).toThrow(/@workflow\/world-postgres/);
+ });
+
+ it("names the incompatible line and the matching install command", () => {
+ let thrown: unknown;
+ try {
+ assertWorkflowWorldCompatibility({
+ worldPackageName: "@workflow/world-postgres",
+ worldManifest: { dependencies: { "@workflow/core": "4.2.0" } },
+ expectedWorkflowVersion: EXPECTED,
+ });
+ } catch (error) {
+ thrown = error;
+ }
+
+ const message = thrown instanceof Error ? thrown.message : String(thrown);
+ expect(message).toContain("@workflow/core 4.x");
+ expect(message).toContain("5.0.0-beta line");
+ expect(message).toContain("pnpm add @workflow/[email protected]");
+ });
+
+ it("passes when the world targets the same prerelease line", () => {
+ expect(() =>
+ assertWorkflowWorldCompatibility({
+ worldPackageName: "@workflow/world-postgres",
+ worldManifest: { dependencies: { "@workflow/core": "5.0.0-beta.20" } },
+ expectedWorkflowVersion: EXPECTED,
+ }),
+ ).not.toThrow();
+ });
+
+ it("passes when the world targets the line via a caret range", () => {
+ expect(() =>
+ assertWorkflowWorldCompatibility({
+ worldPackageName: "@workflow/world-postgres",
+ worldManifest: { dependencies: { "@workflow/core": "^5.0.0-beta.13" } },
+ expectedWorkflowVersion: EXPECTED,
+ }),
+ ).not.toThrow();
+ });
+
+ it("falls back to the @workflow/world dependency when @workflow/core is absent", () => {
+ expect(() =>
+ assertWorkflowWorldCompatibility({
+ worldPackageName: "@workflow/world-postgres",
+ worldManifest: { dependencies: { "@workflow/world": "^4.0.0" } },
+ expectedWorkflowVersion: EXPECTED,
+ }),
+ ).toThrow(/@workflow\/world 4\.x/);
+ });
+
+ it("reads the declared line from peerDependencies", () => {
+ expect(() =>
+ assertWorkflowWorldCompatibility({
+ worldPackageName: "@workflow/world-postgres",
+ worldManifest: { peerDependencies: { "@workflow/core": "^4.0.0" } },
+ expectedWorkflowVersion: EXPECTED,
+ }),
+ ).toThrow(/@workflow\/core 4\.x/);
+ });
+
+ it("no-ops when the world declares no @workflow/* dependency", () => {
+ expect(() =>
+ assertWorkflowWorldCompatibility({
+ worldPackageName: "@workflow/world-postgres",
+ worldManifest: { dependencies: { "some-other-dep": "1.0.0" } },
+ expectedWorkflowVersion: EXPECTED,
+ }),
+ ).not.toThrow();
+ });
+
+ it("no-ops when the declared range is unparseable", () => {
+ expect(() =>
+ assertWorkflowWorldCompatibility({
+ worldPackageName: "@workflow/world-postgres",
+ worldManifest: { dependencies: { "@workflow/core": "workspace:*" } },
+ expectedWorkflowVersion: EXPECTED,
+ }),
+ ).not.toThrow();
+ });
+
+ it("no-ops when the expected version cannot be parsed", () => {
+ expect(() =>
+ assertWorkflowWorldCompatibility({
+ worldPackageName: "@workflow/world-postgres",
+ worldManifest: { dependencies: { "@workflow/core": "^4.0.0" } },
+ expectedWorkflowVersion: "not-a-version",
+ }),
+ ).not.toThrow();
+ });
+});
diff --git a/packages/eve/src/internal/workflow/world-compatibility.ts b/packages/eve/src/internal/workflow/world-compatibility.ts
new file mode 100644
index 000000000..53f02cf95
--- /dev/null
+++ b/packages/eve/src/internal/workflow/world-compatibility.ts
@@ -0,0 +1,144 @@
+/**
+ * The `@workflow/*` packages whose version line a configured world is checked
+ * against, in order of preference. eve compares the world's declared dependency
+ * on the first of these it finds.
+ */
+const WORKFLOW_COMPATIBILITY_PACKAGES = ["@workflow/core", "@workflow/world"] as const;
+
+/**
+ * Minimal subset of an npm `package.json` needed to read a world's declared
+ * `@workflow/*` dependency line.
+ */
+export interface WorkflowWorldManifest {
+ readonly dependencies?: Readonly<Record<string, string>>;
+ readonly peerDependencies?: Readonly<Record<string, string>>;
+}
+
+export interface AssertWorkflowWorldCompatibilityInput {
+ /** Package name of the configured world, used only for the error message. */
+ readonly worldPackageName: string;
+ /** Parsed `package.json` of the installed configured world. */
+ readonly worldManifest: WorkflowWorldManifest;
+ /** The `@workflow/core` version this eve release bundles (its single source of truth). */
+ readonly expectedWorkflowVersion: string;
+}
+
+interface VersionLine {
+ readonly major: number;
+ readonly prereleaseTag: string | undefined;
+}
+
+/**
+ * Parses the leading semver-ish coordinates out of a version or simple range.
+ *
+ * This is intentionally tiny — eve only needs the major number and any
+ * prerelease tag to detect a definite line mismatch, so we avoid pulling in a
+ * full semver parser (keeping `nitro` as eve's only runtime dependency).
+ * Returns `undefined` when the major cannot be determined so callers can no-op
+ * rather than risk a false-positive boot failure.
+ */
+function parseVersionLine(value: string): VersionLine | undefined {
+ // Strip a single leading range operator (`^`, `~`, `>=`, etc.) and any
+ // surrounding whitespace; we only inspect the first concrete version.
+ const match = /(\d+)\.(?:\d+|x|\*)(?:\.(?:\d+|x|\*))?(?:-([0-9A-Za-z.-]+))?/.exec(value.trim());
+
+ if (match === null) {
+ return undefined;
+ }
+
+ const major = Number(match[1]);
+
+ if (!Number.isInteger(major)) {
+ return undefined;
+ }
+
+ const prerelease = match[2];
+ // Reduce `beta.13` / `beta.24` to the line tag `beta` so different patch
+ // builds on the same prerelease line compare equal.
+ const prereleaseTag = prerelease === undefined ? undefined : prerelease.split(".")[0];
+
+ return { major, prereleaseTag };
+}
+
+function readDeclaredWorkflowDependency(
+ manifest: WorkflowWorldManifest,
+): { packageName: string; range: string } | undefined {
+ for (const packageName of WORKFLOW_COMPATIBILITY_PACKAGES) {
+ const range = manifest.dependencies?.[packageName] ?? manifest.peerDependencies?.[packageName];
+
+ if (typeof range === "string" && range.trim().length > 0) {
+ return { packageName, range };
+ }
+ }
+
+ return undefined;
+}
+
+function isDefiniteLineMismatch(world: VersionLine, expected: VersionLine): boolean {
+ if (world.major !== expected.major) {
+ return true;
+ }
+
+ // Same major: a definite mismatch only when both sides declare a prerelease
+ // tag and the tags differ (e.g. `beta` vs `alpha`). A world targeting a
+ // stable release of the same major (no prerelease tag) is treated as
+ // compatible-enough — we only fail on unambiguous divergence.
+ return (
+ world.prereleaseTag !== undefined &&
+ expected.prereleaseTag !== undefined &&
+ world.prereleaseTag !== expected.prereleaseTag
+ );
+}
+
+function formatExpectedLine(line: VersionLine): string {
+ return line.prereleaseTag === undefined
+ ? `${String(line.major)}.x`
+ : `${String(line.major)}.0.0-${line.prereleaseTag} line`;
+}
+
+/**
+ * Fails fast when a configured Workflow world targets a `@workflow/*` major or
+ * prerelease line that is incompatible with the line this eve release bundles.
+ *
+ * The check is deliberately conservative: it throws only on a *definite*
+ * mismatch (a different major version, or a different prerelease tag on the
+ * same major). When the world's declared `@workflow/*` dependency is missing or
+ * its version cannot be parsed, this is a no-op so eve never turns an
+ * ambiguous-but-possibly-fine setup into a hard boot failure. The deeper,
+ * fully version-aware compatibility check belongs in `@workflow/core`; this is
+ * a low-risk early signal that surfaces an actionable message instead of a
+ * cryptic Zod error deep in workflow replay.
+ *
+ * @throws Error when the world declares an incompatible `@workflow/*` line.
+ */
+export function assertWorkflowWorldCompatibility(
+ input: AssertWorkflowWorldCompatibilityInput,
+): void {
+ const declared = readDeclaredWorkflowDependency(input.worldManifest);
+
+ if (declared === undefined) {
+ return;
+ }
+
+ const worldLine = parseVersionLine(declared.range);
+ const expectedLine = parseVersionLine(input.expectedWorkflowVersion);
+
+ if (worldLine === undefined || expectedLine === undefined) {
+ return;
+ }
+
+ if (!isDefiniteLineMismatch(worldLine, expectedLine)) {
+ return;
+ }
+
+ const worldLineLabel =
+ worldLine.prereleaseTag === undefined
+ ? `${String(worldLine.major)}.x`
+ : `${String(worldLine.major)}.x (${worldLine.prereleaseTag} line)`;
+
+ throw new Error(
+ `Configured Workflow world "${input.worldPackageName}" targets ${declared.packageName} ${worldLineLabel}, ` +
+ `but this eve release requires the ${declared.packageName} ${formatExpectedLine(expectedLine)}. ` +
+ `Install a matching world, e.g. \`pnpm add ${input.worldPackageName}@${input.expectedWorkflowVersion}\`.`,
+ );
+}