Validate unique workflow step IDs at build time (#2018)

* Validate unique step ids at build time

* Fall back to file-path IDs for non-exported package files

Instead of synthesizing a 'name/dist/<path>@Version' specifier (which
hardcoded the dist/ output convention), non-exported workspace/node_modules
files now return moduleSpecifier: undefined and let the SWC plugin's
'./{filepath}' fallback produce per-file IDs. This is the same path local
app files have always taken and avoids the dist/ assumption flagged in
review. The build-time duplicate-ID check stays as the safety net.

* Dedupe virtual-entry imports by canonical module identity

When both the source and the compiled-dist copies of the same workspace
package export end up in discoveredSteps/discoveredWorkflows (e.g. the
'workflow' package's internal/builtins in monorepo dev), they resolve to
the same module via esbuild's package resolution. The virtual entry was
emitting BOTH 'import "workflow/internal/builtins";' (the built-in
preamble) and 'import "../../packages/workflow/src/internal/builtins.ts";'
(via the isWorkspaceSourceBackedPackageFile carve-out in createImport),
which made the swc plugin transform both copies and generate duplicate
step IDs.

Track a per-bundle set of emitted module identities (package specifier
when reachable, otherwise the file path) and skip files whose identity
has already been imported. The steps bundle pre-seeds the set with the
built-in steps specifier so workspace step files at that path don't
emit a competing relative-path import.

* Stop rewriting workspace package /dist/ -> /src/ during Next.js discovery

The Next.js deferred builder's `resolveSourceBackedPackagePath` rewrote
any discovered `/dist/` path to its `/src/` sibling for workspace
packages and for `workflow`/`@workflow/*` tarballs. That made the
discovered step file list point at source files while base-builder's
esbuild bundle (which builds the workflow VM and step registrations)
resolved the same package imports through `pkg.exports` to
`/dist/`. The workflow proxy ID — generated from the dist path —
didn't match the step bundle's registration ID — generated from the
src path — producing "Step function not registered" failures at
runtime, most visibly with @workflow/ai's doStreamStep on Vercel and
Windows Next.js deployments.

App code that imports a package by name should resolve naturally
through pkg.exports; the loader has no business reaching into the
package's source tree. Drop the rewrite (and the now-unused
`resolveCopiedStepImportTargetPath` helper that supported it).
Workspace packages are still discovered — that's a separate predicate
(`shouldPreferSourceBackedPackagePath`) which only gates inclusion,
not path translation.

Verified locally with the nextjs-turbopack workbench: agent e2e suite
(19 tests, including the failing `agentBasicE2e`) and the
addTenWorkflow duplicate-name suite all pass.

* Address review nits: extract stripPackageVersion, expand duplicate-ID hint, note new build-time check in changeset

---------

Co-authored-by: Nathan Rajlich <n@n8.io>
Co-authored-by: Peter Wielander <mittgfu@gmail.com>

Author: 3 people

.changeset/next-respect-package-exports.md

@@ -0,0 +1,5 @@
+---
+"@workflow/next": patch
+---
+
+Stop rewriting workspace-package `/dist/` paths to `/src/` during workflow/step discovery so that the discovered file paths agree with how base-builder resolves the same packages through `pkg.exports`, fixing `Step function not registered` errors at runtime.

.changeset/validate-step-id-duplicates.md

@@ -0,0 +1,5 @@
+---
+"@workflow/builders": patch
+---
+
+Generate per-file IDs for non-exported workspace package files (previously they collapsed to `name@version` and silently overwrote each other at runtime) and fail the build when two transformed files emit the same step or workflow ID — collisions that used to register silently last-write-wins now surface as a build error.

packages/builders/src/base-builder.ts

@@ -16,7 +16,11 @@ import {
 } from './apply-swc-transform.js';
 import { createDiscoverEntriesPlugin } from './discover-entries-esbuild-plugin.js';
 import { getEsbuildTsconfigOptions } from './esbuild-tsconfig.js';
-import { getImportPath } from './module-specifier.js';
+import {
+  getImportPath,
+  resolveModuleSpecifier,
+  stripPackageVersion,
+} from './module-specifier.js';
 import { createNodeModuleErrorPlugin } from './node-module-esbuild-plugin.js';
 import { createPseudoPackagePlugin } from './pseudo-package-esbuild-plugin.js';
 import { createSwcPlugin } from './swc-esbuild-plugin.js';
@@ -90,6 +94,31 @@ async function withRealpaths(entries: string[]): Promise<string[]> {
   );
 }
 
+/**
+ * Canonical "what module does this file represent?" key used to dedupe
+ * virtual-entry imports.
+ *
+ * If the file resolves to a real package specifier (`workflow/internal/builtins`,
+ * `@internal/agent/server`, etc.), we return the bare specifier — version
+ * stripped — because esbuild's package resolution will collapse all
+ * importers of that specifier to the same physical module regardless of
+ * which on-disk copy (src vs dist) any one importer wrote.
+ *
+ * Otherwise we fall back to the absolute file path. Distinct local-app
+ * files have distinct paths, so this still dedupes a file against itself
+ * (e.g. if it shows up in both `stepFiles` and `serdeOnlyFiles`) without
+ * conflating unrelated files.
+ */
+function moduleIdentityKey(file: string, projectRoot: string): string {
+  const { moduleSpecifier } = resolveModuleSpecifier(file, projectRoot);
+  if (moduleSpecifier) {
+    // Strip the "@<version>" suffix so source and dist copies of the same
+    // export collapse to the same key.
+    return stripPackageVersion(moduleSpecifier);
+  }
+  return file.replace(/\\/g, '/');
+}
+
 export interface DiscoveredEntries {
   discoveredSteps: Set<string>;
   discoveredWorkflows: Set<string>;
@@ -696,10 +725,29 @@ export abstract class BaseBuilder {
 
     // Create a virtual entry that imports all files. All step definitions
     // will get registered thanks to the swc transform.
-    const stepImports = stepFiles.map(createImport).join('\n');
+    //
+    // Dedupe imports by canonical module identity so we never emit two
+    // import lines that resolve to the same physical module. Pre-seed the
+    // set with the built-in steps import so a workspace step file at
+    // `packages/workflow/src/internal/builtins.ts` doesn't emit a second,
+    // relative-path competing import — esbuild would otherwise transform
+    // both copies and the swc plugin would generate duplicate step IDs.
+    const emittedImportIdentities = new Set<string>([builtInSteps]);
+    const buildImports = (files: string[]): string =>
+      files
+        .filter((file) => {
+          const identity = moduleIdentityKey(file, this.transformProjectRoot);
+          if (emittedImportIdentities.has(identity)) return false;
+          emittedImportIdentities.add(identity);
+          return true;
+        })
+        .map(createImport)
+        .join('\n');
+
+    const stepImports = buildImports(stepFiles);
 
     // Include serde-only files for class registration side effects
-    const serdeImports = serdeOnlyFiles.map(createImport).join('\n');
+    const serdeImports = buildImports(serdeOnlyFiles);
 
     const entryContent = `
     // Built in steps
@@ -934,13 +982,28 @@ export abstract class BaseBuilder {
       return `import '${relativePath}';`;
     };
 
-    // Create a virtual entry that imports all workflow files
+    // Create a virtual entry that imports all workflow files. Dedupe by
+    // canonical module identity so source/dist copies of the same workspace
+    // package export don't both get imported (which would make the swc
+    // plugin generate duplicate workflow IDs).
+    const emittedImportIdentities = new Set<string>();
+    const buildImports = (files: string[]): string =>
+      files
+        .filter((file) => {
+          const identity = moduleIdentityKey(file, this.transformProjectRoot);
+          if (emittedImportIdentities.has(identity)) return false;
+          emittedImportIdentities.add(identity);
+          return true;
+        })
+        .map(createImport)
+        .join('\n');
+
     // The SWC plugin in workflow mode emits `globalThis.__private_workflows.set(workflowId, fn)`
     // calls directly, so we just need to import the files (Map is initialized via banner)
-    const workflowImports = workflowFiles.map(createImport).join('\n');
+    const workflowImports = buildImports(workflowFiles);
 
     // Include serde-only files for class registration side effects
-    const serdeImports = serdeOnlyFiles.map(createImport).join('\n');
+    const serdeImports = buildImports(serdeOnlyFiles);
 
     const imports = serdeImports
       ? `${workflowImports}\n// Serde files for cross-context class registration\n${serdeImports}`

packages/builders/src/module-specifier.test.ts

@@ -281,7 +281,30 @@ describe('getImportPath', () => {
     });
   });
 
-  it('uses the consuming app root to resolve workspace package workflow ids', () => {
+  it('uses package specifiers for workspace package root entrypoint ids', () => {
+    const projectRoot = join(testRoot, 'apps/chat');
+    const packageDir = join(testRoot, 'packages/vade');
+    const filePath = join(packageDir, 'src/index.ts');
+
+    writeJson(join(projectRoot, 'package.json'), {
+      name: 'chat',
+      dependencies: { vade: 'workspace:*' },
+    });
+
+    writeJson(join(packageDir, 'package.json'), {
+      name: 'vade',
+      version: '0.0.0',
+      main: './src/index.ts',
+    });
+
+    writeFile(filePath, `'use workflow';\n`);
+
+    expect(resolveModuleSpecifier(filePath, projectRoot)).toEqual({
+      moduleSpecifier: 'vade@0.0.0',
+    });
+  });
+
+  it('returns undefined for non-exported workspace package files', () => {
     const projectRoot = join(testRoot, 'apps/chat');
     const packageDir = join(testRoot, 'packages/vade');
     const filePath = join(
@@ -301,8 +324,12 @@ describe('getImportPath', () => {
 
     writeFile(filePath, `'use workflow';\n`);
 
+    // Non-exported package files fall back to the relative-file-path ID
+    // (the SWC plugin uses "./{file}" when moduleSpecifier is undefined).
+    // This keeps IDs unique per file across the build instead of collapsing
+    // every non-exported file in `vade` to the same "vade@0.0.0" specifier.
     expect(resolveModuleSpecifier(filePath, projectRoot)).toEqual({
-      moduleSpecifier: 'vade@0.0.0',
+      moduleSpecifier: undefined,
     });
   });
 

packages/builders/src/module-specifier.ts

@@ -338,11 +338,16 @@ function isWorkspacePackage(filePath: string, projectRoot: string): boolean {
  * // => { moduleSpecifier: 'workflow/internal/builtins@4.0.0' }
  *
  * @example
- * // File in workspace package
- * resolveModuleSpecifier('/project/packages/shared/src/utils.ts', '/project')
+ * // Exported root file in workspace package
+ * resolveModuleSpecifier('/project/packages/shared/src/index.ts', '/project')
  * // => { moduleSpecifier: '@myorg/shared@0.0.0' }
  *
  * @example
+ * // Non-exported / deep package file
+ * resolveModuleSpecifier('/project/packages/shared/src/internal/foo.ts', '/project')
+ * // => { moduleSpecifier: undefined }
+ *
+ * @example
  * // Local app file
  * resolveModuleSpecifier('/project/src/workflows/order.ts', '/project')
  * // => { moduleSpecifier: undefined }
@@ -373,16 +378,50 @@ export function resolveModuleSpecifier(
     allowSourceFallback: true,
   });
 
-  // Return the module specifier as "name/subpath@version" or "name@version"
-  const specifier = subpath
-    ? `${pkg.name}${subpath}@${pkg.version}`
-    : `${pkg.name}@${pkg.version}`;
+  if (subpath) {
+    return {
+      moduleSpecifier: `${pkg.name}${subpath}@${pkg.version}`,
+    };
+  }
+
+  if (isRootEntrypointFile(filePath, pkg)) {
+    return {
+      moduleSpecifier: `${pkg.name}@${pkg.version}`,
+    };
+  }
 
+  // Non-exported package file (deep import that isn't reachable as a
+  // package specifier). Returning undefined makes the SWC plugin fall back
+  // to the relative file path, which keeps IDs unique per file. Previously
+  // every non-exported file collapsed to "name@version", causing same-named
+  // step/workflow functions in different files to silently overwrite each
+  // other at runtime registration; the build-time duplicate-ID check now
+  // also catches that class of collision.
   return {
-    moduleSpecifier: specifier,
+    moduleSpecifier: undefined,
   };
 }
 
+/**
+ * Strip the trailing "@<version>" suffix from a module specifier produced by
+ * `resolveModuleSpecifier`, leaving the bare `name` or `name/subpath` form.
+ *
+ * Use this when you want to compare or dedupe specifiers across versions
+ * (e.g. treating `@workflow/ai/agent@5.0.0-beta.4` and
+ * `@workflow/ai/agent@5.0.0-beta.5` as the same logical module).
+ *
+ * Colocated with `resolveModuleSpecifier` so the construction and parsing
+ * stay in sync — see the `${pkg.name}${subpath}@${pkg.version}` and
+ * `${pkg.name}@${pkg.version}` paths above.
+ */
+export function stripPackageVersion(specifier: string): string {
+  // The version is always the final segment after the last "@". Constrain
+  // matching to characters that can't appear in a package name or subpath
+  // (no "/", no nested "@") so scoped packages like `@workflow/ai@1.0.0`
+  // keep their leading "@workflow/ai".
+  return specifier.replace(/@[^/@]+$/, '');
+}
+
 /**
  * Clear the package.json cache. Useful for testing or when package.json files may have changed.
  */

packages/builders/src/swc-esbuild-plugin.test.ts

@@ -51,6 +51,88 @@ describe('createSwcPlugin externalizeNonSteps', () => {
     rmSync(testRoot, { recursive: true, force: true });
   });
 
+  it('fails the build when two files emit the same step id', async () => {
+    const srcDir = join(testRoot, 'src');
+    const firstStepFile = join(srcDir, 'confirmation.ts');
+    const secondStepFile = join(srcDir, 'reschedule.ts');
+
+    writeFile(firstStepFile, `export const first = true;`);
+    writeFile(secondStepFile, `export const second = true;`);
+
+    applySwcTransformMock.mockImplementation(
+      async (filename: string, source: string) => ({
+        code: source,
+        workflowManifest: {
+          steps: {
+            [filename]: {
+              sendMessage: {
+                stepId: 'step//shared-package@1.0.0//sendMessage',
+              },
+            },
+          },
+        },
+      })
+    );
+
+    await expect(
+      esbuild.build({
+        entryPoints: [firstStepFile, secondStepFile],
+        absWorkingDir: testRoot,
+        outdir: join(testRoot, 'out'),
+        bundle: true,
+        format: 'esm',
+        platform: 'node',
+        write: false,
+        plugins: [
+          createSwcPlugin({
+            mode: 'step',
+          }),
+        ],
+      })
+    ).rejects.toThrow(/Duplicate workflow step ID/);
+  });
+
+  it('fails the build when two files emit the same workflow id', async () => {
+    const srcDir = join(testRoot, 'src');
+    const firstWorkflowFile = join(srcDir, 'confirmation.ts');
+    const secondWorkflowFile = join(srcDir, 'reschedule.ts');
+
+    writeFile(firstWorkflowFile, `export const first = true;`);
+    writeFile(secondWorkflowFile, `export const second = true;`);
+
+    applySwcTransformMock.mockImplementation(
+      async (filename: string, source: string) => ({
+        code: source,
+        workflowManifest: {
+          workflows: {
+            [filename]: {
+              sendMessage: {
+                workflowId: 'workflow//shared-package@1.0.0//sendMessage',
+              },
+            },
+          },
+        },
+      })
+    );
+
+    await expect(
+      esbuild.build({
+        entryPoints: [firstWorkflowFile, secondWorkflowFile],
+        absWorkingDir: testRoot,
+        outdir: join(testRoot, 'out'),
+        bundle: true,
+        format: 'esm',
+        platform: 'node',
+        write: false,
+        plugins: [
+          createSwcPlugin({
+            mode: 'workflow',
+          }),
+        ],
+      })
+    ).rejects.toThrow(/Duplicate workflow ID/);
+  });
+
   it.each([
     { inputExt: '.ts', outputExt: '.js' },
     { inputExt: '.tsx', outputExt: '.js' },