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.mdnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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 themdiff --git a/packages/eve/src/internal/workflow/configure-world.ts b/packages/eve/src/internal/workflow/configure-world.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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}\`.`,+ );+}