@output.ai/core 0.5.2 → 0.5.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@output.ai/core",
-  "version": "0.5.2",
+  "version": "0.5.3",
   "description": "The core module of the output framework",
   "type": "module",
   "exports": {

package/src/interface/workflow.js

@@ -80,6 +80,7 @@ export function workflow( { name, description, inputSchema, outputSchema, fn, op
         invokeStep: async ( stepName, input, options ) => steps[`${name}#${stepName}`]( input, options ),
         invokeSharedStep: async ( stepName, input, options ) => steps[`${SHARED_STEP_PREFIX}#${stepName}`]( input, options ),
         invokeEvaluator: async ( evaluatorName, input, options ) => steps[`${name}#${evaluatorName}`]( input, options ),
+        invokeSharedEvaluator: async ( evaluatorName, input, options ) => steps[`${SHARED_STEP_PREFIX}#${evaluatorName}`]( input, options ),
 
         /**
          * Start a child workflow

package/src/tracing/tools/build_trace_tree.js

@@ -23,7 +23,7 @@ const createEntry = id => ( {
   kind: '',
   name: '',
   startedAt: 0,
-  endedAt: 0,
+  endedAt: null,
   input: undefined,
   output: undefined,
   error: undefined,
@@ -75,5 +75,9 @@ export default entries => {
   if ( !rootNode ) {
     return null;
   }
+  if ( !rootNode.endedAt ) {
+    rootNode.output = '<<Workflow did not finish yet. If this workflows is supposed to have been completed already, \
+this can indicate it timed out or was interrupted.>>';
+  }
   return rootNode;
 };

package/src/tracing/tools/build_trace_tree.spec.js

@@ -6,6 +6,17 @@ describe( 'build_trace_tree', () => {
     expect( buildTraceTree( [] ) ).toBeNull();
   } );
 
+  it( 'sets root output with a fixed message when workflow has no end/error phase yet', () => {
+    const entries = [
+      { kind: 'workflow', id: 'wf', parentId: undefined, phase: 'start', name: 'wf', details: {}, timestamp: 1000 }
+    ];
+    const result = buildTraceTree( entries );
+    expect( result ).not.toBeNull();
+    expect( result.output ).toBe( '<<Workflow did not finish yet. If this workflows is supposed to have been completed already, \
+this can indicate it timed out or was interrupted.>>' );
+    expect( result.endedAt ).toBeNull();
+  } );
+
   it( 'returns null when there is no root (all entries have parentId)', () => {
     const entries = [
       { id: 'a', parentId: 'x', phase: 'start', name: 'a', timestamp: 1 },

package/src/worker/catalog_workflow/workflow.js

@@ -1,4 +1,4 @@
-import { defineQuery, setHandler, condition } from '@temporalio/workflow';
+import { defineQuery, setHandler, condition, defineUpdate } from '@temporalio/workflow';
 
 /**
  * This is a special workflow, unique to each worker, which holds the meta information of all other workflows in that worker.
@@ -8,7 +8,13 @@ import { defineQuery, setHandler, condition } from '@temporalio/workflow';
  * @param {object} catalog - The catalog information
  */
 export default async function catalogWorkflow( catalog ) {
+  const state = { canEnd: false };
+
   setHandler( defineQuery( 'get' ), () => catalog );
-  // Wait indefinitely but remain responsive to workflow cancellation
-  await condition( () => false );
+
+  // Listen to this update to complete the workflow
+  setHandler( defineUpdate( 'complete' ), () => state.canEnd = true );
+
+  // Wait indefinitely, until the state changes
+  await condition( () => state.canEnd );
 };

package/src/worker/index.js

@@ -1,15 +1,14 @@
 import { Worker, NativeConnection } from '@temporalio/worker';
-import { Client } from '@temporalio/client';
-import { WorkflowIdConflictPolicy } from '@temporalio/common';
 import * as configs from './configs.js';
 import { loadActivities, loadWorkflows, createWorkflowsEntryPoint } from './loader.js';
 import { sinks } from './sinks.js';
 import { createCatalog } from './catalog_workflow/index.js';
 import { init as initTracing } from '#tracing';
-import { WORKFLOW_CATALOG } from '#consts';
 import { webpackConfigHook } from './bundler_options.js';
 import { initInterceptors } from './interceptors.js';
 import { createChildLogger } from '#logger';
+import { registerShutdown } from './shutdown.js';
+import { startCatalog } from './start_catalog.js';
 
 const log = createChildLogger( 'Worker' );
 
@@ -22,7 +21,6 @@ const callerDir = process.argv[2];
     apiKey,
     namespace,
     taskQueue,
-    catalogId,
     maxConcurrentWorkflowTaskExecutions,
     maxConcurrentActivityTaskExecutions,
     maxCachedWorkflows,
@@ -66,45 +64,15 @@ const callerDir = process.argv[2];
     bundlerOptions: { webpackConfigHook }
   } );
 
-  log.info( 'Starting catalog workflow...' );
-  await new Client( { connection, namespace } ).workflow.start( WORKFLOW_CATALOG, {
-    taskQueue,
-    workflowId: catalogId, // use the name of the task queue as the catalog name, ensuring uniqueness
-    workflowIdConflictPolicy: WorkflowIdConflictPolicy.TERMINATE_EXISTING,
-    args: [ catalog ]
-  } );
+  registerShutdown( { worker, log } );
 
   log.info( 'Running worker...' );
+  await Promise.all( [ worker.run(), startCatalog( { connection, namespace, catalog } ) ] );
 
-  // FORCE_QUIT_GRACE_MS delays the second instance of a shutdown command.
-  // If running output-worker directly with npx, 2 signals are recieved in
-  // rapid succession, and users see the force quit message.
-  const FORCE_QUIT_GRACE_MS = 1000;
-  const state = { isShuttingDown: false, shutdownStartedAt: null };
-
-  const shutdown = signal => {
-    if ( state.isShuttingDown ) {
-      const elapsed = Date.now() - state.shutdownStartedAt;
-      if ( elapsed < FORCE_QUIT_GRACE_MS ) {
-        return; // ignore rapid duplicate signals
-      }
-      log.warn( 'Force quitting...' );
-      process.exit( 1 );
-    }
-    state.isShuttingDown = true;
-    state.shutdownStartedAt = Date.now();
-    log.info( 'Shutting down...', { signal } );
-    worker.shutdown();
-  };
-
-  process.on( 'SIGTERM', () => shutdown( 'SIGTERM' ) );
-  process.on( 'SIGINT', () => shutdown( 'SIGINT' ) );
-
-  await worker.run();
-  log.info( 'Worker stopped.' );
-
+  log.info( 'Closing connection...' );
   await connection.close();
-  log.info( 'Connection closed.' );
+
+  log.info( 'Bye' );
 
   process.exit( 0 );
 } )().catch( error => {

package/src/worker/index.spec.js

@@ -40,6 +40,12 @@ vi.mock( './bundler_options.js', () => ( { webpackConfigHook: vi.fn() } ) );
 const initInterceptorsMock = vi.fn().mockReturnValue( [] );
 vi.mock( './interceptors.js', () => ( { initInterceptors: initInterceptorsMock } ) );
 
+const startCatalogMock = vi.fn().mockResolvedValue( undefined );
+vi.mock( './start_catalog.js', () => ( { startCatalog: startCatalogMock } ) );
+
+const registerShutdownMock = vi.fn();
+vi.mock( './shutdown.js', () => ( { registerShutdown: registerShutdownMock } ) );
+
 const runState = { resolve: null };
 const runPromise = new Promise( r => {
   runState.resolve = r;
@@ -53,22 +59,10 @@ vi.mock( '@temporalio/worker', () => ( {
   NativeConnection: { connect: vi.fn().mockResolvedValue( mockConnection ) }
 } ) );
 
-const workflowStartMock = vi.fn().mockResolvedValue( undefined );
-vi.mock( '@temporalio/client', () => ( {
-  Client: vi.fn().mockImplementation( () => ( {
-    workflow: { start: workflowStartMock }
-  } ) )
-} ) );
-
-vi.mock( '@temporalio/common', () => ( {
-  WorkflowIdConflictPolicy: { TERMINATE_EXISTING: 'TERMINATE_EXISTING' }
-} ) );
-
 describe( 'worker/index', () => {
   const exitMock = vi.fn();
   const originalArgv = process.argv;
   const originalExit = process.exit;
-  const originalOn = process.on;
 
   beforeEach( () => {
     vi.clearAllMocks();
@@ -79,13 +73,11 @@ describe( 'worker/index', () => {
   afterEach( () => {
     process.argv = originalArgv;
     process.exit = originalExit;
-    process.on = originalOn;
     configValues.apiKey = undefined;
   } );
 
   it( 'loads configs, workflows, activities and creates worker with correct options', async () => {
     const { Worker, NativeConnection } = await import( '@temporalio/worker' );
-    const { Client } = await import( '@temporalio/client' );
     const { init: initTracing } = await import( '#tracing' );
 
     import( './index.js' );
@@ -114,12 +106,11 @@ describe( 'worker/index', () => {
       maxConcurrentWorkflowTaskPolls: configValues.maxConcurrentWorkflowTaskPolls
     } ) );
     expect( initInterceptorsMock ).toHaveBeenCalledWith( { activities: {} } );
-    expect( Client ).toHaveBeenCalledWith( { connection: mockConnection, namespace: configValues.namespace } );
-    expect( workflowStartMock ).toHaveBeenCalledWith( 'catalog', {
-      taskQueue: configValues.taskQueue,
-      workflowId: configValues.catalogId,
-      workflowIdConflictPolicy: 'TERMINATE_EXISTING',
-      args: [ { workflows: [], activities: {} } ]
+    expect( registerShutdownMock ).toHaveBeenCalledWith( { worker: mockWorker, log: mockLog } );
+    expect( startCatalogMock ).toHaveBeenCalledWith( {
+      connection: mockConnection,
+      namespace: configValues.namespace,
+      catalog: { workflows: [], activities: {} }
     } );
 
     runState.resolve();
@@ -145,23 +136,14 @@ describe( 'worker/index', () => {
     await vi.waitFor( () => expect( exitMock ).toHaveBeenCalled() );
   } );
 
-  it( 'registers SIGTERM and SIGINT handlers that shut down worker', async () => {
-    const onMock = vi.fn();
-    process.on = onMock;
+  it( 'calls registerShutdown with worker and log', async () => {
     vi.resetModules();
 
     import( './index.js' );
 
     await vi.waitFor( () => {
-      expect( onMock ).toHaveBeenCalledWith( 'SIGTERM', expect.any( Function ) );
-      expect( onMock ).toHaveBeenCalledWith( 'SIGINT', expect.any( Function ) );
+      expect( registerShutdownMock ).toHaveBeenCalledWith( { worker: mockWorker, log: mockLog } );
     } );
-
-    const sigtermHandler = onMock.mock.calls.find( c => c[0] === 'SIGTERM' )?.[1];
-    expect( sigtermHandler ).toBeDefined();
-    sigtermHandler();
-    expect( shutdownMock ).toHaveBeenCalled();
-
     runState.resolve();
     await vi.waitFor( () => expect( exitMock ).toHaveBeenCalled() );
   } );

package/src/worker/interceptors/workflow.js

@@ -49,7 +49,7 @@ class WorkflowExecutionInterceptor {
       }
 
       sinks.trace.addWorkflowEventError( error );
-      const failure = new ApplicationFailure( error.message, error.constructor.name );
+      const failure = new ApplicationFailure( error.message, error.constructor.name, undefined, undefined, error );
 
       /*
        * If intercepted error has metadata, set it to .details property of Temporal's ApplicationFailure instance.

package/src/worker/shutdown.js

@@ -0,0 +1,26 @@
+const FORCE_QUIT_GRACE_MS = 1000;
+
+export const registerShutdown = ( { worker, log } ) => {
+  const state = { isShuttingDown: false, shutdownStartedAt: null };
+
+  const shutdown = signal => {
+    if ( state.isShuttingDown ) {
+      const elapsed = Date.now() - state.shutdownStartedAt;
+
+      // If running with npx, 2 kill signals are received in rapid succession,
+      // this ignores the second interruption when it is right after the first.
+      if ( elapsed < FORCE_QUIT_GRACE_MS ) {
+        return;
+      }
+      log.warn( 'Force quitting...' );
+      process.exit( 1 );
+    }
+    state.isShuttingDown = true;
+    state.shutdownStartedAt = Date.now();
+    log.info( 'Shutting down...', { signal } );
+    worker.shutdown();
+  };
+
+  process.on( 'SIGTERM', () => shutdown( 'SIGTERM' ) );
+  process.on( 'SIGINT', () => shutdown( 'SIGINT' ) );
+};

package/src/worker/shutdown.spec.js

@@ -0,0 +1,82 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { registerShutdown } from './shutdown.js';
+
+describe( 'worker/shutdown', () => {
+  const mockLog = { info: vi.fn(), warn: vi.fn() };
+  const shutdownMock = vi.fn();
+  const mockWorker = { shutdown: shutdownMock };
+  const onHandlers = {};
+  const exitMock = vi.fn();
+  const originalOn = process.on;
+  const originalExit = process.exit;
+
+  beforeEach( () => {
+    vi.clearAllMocks();
+    Object.keys( onHandlers ).forEach( k => delete onHandlers[k] );
+    process.on = vi.fn( ( event, handler ) => {
+      onHandlers[event] = handler;
+    } );
+    process.exit = exitMock;
+  } );
+
+  afterEach( () => {
+    process.on = originalOn;
+    process.exit = originalExit;
+  } );
+
+  it( 'registers SIGTERM and SIGINT handlers', () => {
+    registerShutdown( { worker: mockWorker, log: mockLog } );
+
+    expect( process.on ).toHaveBeenCalledWith( 'SIGTERM', expect.any( Function ) );
+    expect( process.on ).toHaveBeenCalledWith( 'SIGINT', expect.any( Function ) );
+  } );
+
+  it( 'on first signal: logs, calls worker.shutdown(), does not exit', () => {
+    registerShutdown( { worker: mockWorker, log: mockLog } );
+
+    onHandlers.SIGTERM();
+
+    expect( mockLog.info ).toHaveBeenCalledWith( 'Shutting down...', { signal: 'SIGTERM' } );
+    expect( shutdownMock ).toHaveBeenCalledTimes( 1 );
+    expect( mockLog.warn ).not.toHaveBeenCalled();
+    expect( exitMock ).not.toHaveBeenCalled();
+  } );
+
+  it( 'on first SIGINT: logs with SIGINT', () => {
+    registerShutdown( { worker: mockWorker, log: mockLog } );
+
+    onHandlers.SIGINT();
+
+    expect( mockLog.info ).toHaveBeenCalledWith( 'Shutting down...', { signal: 'SIGINT' } );
+    expect( shutdownMock ).toHaveBeenCalledTimes( 1 );
+  } );
+
+  it( 'on second signal within grace period: ignores (no force quit)', () => {
+    vi.useFakeTimers();
+    registerShutdown( { worker: mockWorker, log: mockLog } );
+
+    onHandlers.SIGTERM();
+    onHandlers.SIGINT();
+
+    expect( mockLog.info ).toHaveBeenCalledTimes( 1 );
+    expect( shutdownMock ).toHaveBeenCalledTimes( 1 );
+    expect( mockLog.warn ).not.toHaveBeenCalled();
+    expect( exitMock ).not.toHaveBeenCalled();
+
+    vi.useRealTimers();
+  } );
+
+  it( 'on second signal after grace period: logs force quit and exits with 1', () => {
+    vi.useFakeTimers();
+    registerShutdown( { worker: mockWorker, log: mockLog } );
+
+    onHandlers.SIGTERM();
+    vi.advanceTimersByTime( 1001 );
+    onHandlers.SIGINT();
+
+    expect( mockLog.warn ).toHaveBeenCalledWith( 'Force quitting...' );
+    expect( exitMock ).toHaveBeenCalledWith( 1 );
+
+    vi.useRealTimers();
+  } );
+} );

package/src/worker/start_catalog.js

@@ -0,0 +1,36 @@
+import { Client, WorkflowNotFoundError } from '@temporalio/client';
+import { WorkflowIdConflictPolicy } from '@temporalio/common';
+import { WORKFLOW_CATALOG } from '#consts';
+import { catalogId, taskQueue } from './configs.js';
+import { createChildLogger } from '#logger';
+
+const log = createChildLogger( 'Catalog' );
+
+export const startCatalog = async ( { connection, namespace, catalog } ) => {
+  const client = new Client( { connection, namespace } );
+  const catalogWorkflowHandle = client.workflow.getHandle( catalogId );
+
+  try {
+    const catalogWorkflowDescription = await catalogWorkflowHandle.describe();
+    if ( !catalogWorkflowDescription.closeTime ) {
+      log.info( 'Completing previous catalog workflow...' );
+      await catalogWorkflowHandle.executeUpdate( 'complete', { args: [] } );
+    }
+  } catch ( error ) {
+    // When "not found", it's either a cold start or the catalog was already stopped/terminated, ignore it.
+    // Otherwise, create a log and try the next operation:
+    // A. If the workflow is still running, the start() will fail and throw;
+    // B. If the workflow is no running, the start() will succeed, and the error was transient;
+    if ( !( error instanceof WorkflowNotFoundError ) ) {
+      log.warn( 'Error interacting with previous catalog workflow', { error } );
+    }
+  }
+
+  log.info( 'Starting catalog workflow...' );
+  await client.workflow.start( WORKFLOW_CATALOG, {
+    taskQueue,
+    workflowId: catalogId, // use the name of the task queue as the catalog name, ensuring uniqueness
+    workflowIdConflictPolicy: WorkflowIdConflictPolicy.FAIL,
+    args: [ catalog ]
+  } );
+};

package/src/worker/start_catalog.spec.js

@@ -0,0 +1,116 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { WorkflowNotFoundError } from '@temporalio/client';
+
+const mockLog = { info: vi.fn(), warn: vi.fn(), error: vi.fn() };
+vi.mock( '#logger', () => ( { createChildLogger: () => mockLog } ) );
+
+vi.mock( '#consts', () => ( { WORKFLOW_CATALOG: 'catalog' } ) );
+
+const catalogId = 'test-catalog';
+const taskQueue = 'test-queue';
+vi.mock( './configs.js', () => ( { catalogId, taskQueue } ) );
+
+const describeMock = vi.fn();
+const executeUpdateMock = vi.fn();
+const workflowStartMock = vi.fn().mockResolvedValue( undefined );
+vi.mock( '@temporalio/client', async importOriginal => {
+  const actual = await importOriginal();
+  return {
+    ...actual,
+    Client: vi.fn().mockImplementation( () => ( {
+      workflow: {
+        start: workflowStartMock,
+        getHandle: () => ( { describe: describeMock, executeUpdate: executeUpdateMock } )
+      }
+    } ) )
+  };
+} );
+
+vi.mock( '@temporalio/common', () => ( { WorkflowIdConflictPolicy: { FAIL: 'FAIL' } } ) );
+
+describe( 'worker/start_catalog', () => {
+  const mockConnection = {};
+  const namespace = 'default';
+  const catalog = { workflows: [], activities: {} };
+
+  beforeEach( () => {
+    vi.clearAllMocks();
+    workflowStartMock.mockResolvedValue( undefined );
+  } );
+
+  it( 'when previous catalog still running: completes it then starts catalog workflow', async () => {
+    describeMock.mockResolvedValue( { closeTime: undefined } );
+    executeUpdateMock.mockResolvedValue( undefined );
+
+    const { startCatalog } = await import( './start_catalog.js' );
+    await startCatalog( { connection: mockConnection, namespace, catalog } );
+
+    expect( describeMock ).toHaveBeenCalled();
+    expect( mockLog.info ).toHaveBeenCalledWith( 'Completing previous catalog workflow...' );
+    expect( executeUpdateMock ).toHaveBeenCalledWith( 'complete', { args: [] } );
+    expect( mockLog.info ).toHaveBeenCalledWith( 'Starting catalog workflow...' );
+    expect( workflowStartMock ).toHaveBeenCalledWith( 'catalog', {
+      taskQueue,
+      workflowId: catalogId,
+      workflowIdConflictPolicy: 'FAIL',
+      args: [ catalog ]
+    } );
+  } );
+
+  it( 'when no previous catalog: ignores and starts catalog workflow', async () => {
+    describeMock.mockRejectedValue( new WorkflowNotFoundError( 'not found' ) );
+
+    const { startCatalog } = await import( './start_catalog.js' );
+    await startCatalog( { connection: mockConnection, namespace, catalog } );
+
+    expect( describeMock ).toHaveBeenCalled();
+    expect( mockLog.warn ).not.toHaveBeenCalled();
+    expect( mockLog.info ).toHaveBeenCalledWith( 'Starting catalog workflow...' );
+    expect( executeUpdateMock ).not.toHaveBeenCalled();
+    expect( workflowStartMock ).toHaveBeenCalledWith( 'catalog', {
+      taskQueue,
+      workflowId: catalogId,
+      workflowIdConflictPolicy: 'FAIL',
+      args: [ catalog ]
+    } );
+  } );
+
+  it( 'when previous catalog already closed: skips complete and starts catalog workflow', async () => {
+    describeMock.mockResolvedValue( { closeTime: '2024-01-01T00:00:00Z' } );
+
+    const { startCatalog } = await import( './start_catalog.js' );
+    await startCatalog( { connection: mockConnection, namespace, catalog } );
+
+    expect( describeMock ).toHaveBeenCalled();
+    expect( mockLog.info ).not.toHaveBeenCalledWith( 'Completing previous catalog workflow...' );
+    expect( executeUpdateMock ).not.toHaveBeenCalled();
+    expect( mockLog.info ).toHaveBeenCalledWith( 'Starting catalog workflow...' );
+    expect( workflowStartMock ).toHaveBeenCalledWith( 'catalog', {
+      taskQueue,
+      workflowId: catalogId,
+      workflowIdConflictPolicy: 'FAIL',
+      args: [ catalog ]
+    } );
+  } );
+
+  it( 'when describe or complete fails with other error: logs warn and still starts catalog workflow', async () => {
+    describeMock.mockResolvedValue( { closeTime: undefined } );
+    executeUpdateMock.mockRejectedValue( new Error( 'Connection refused' ) );
+
+    const { startCatalog } = await import( './start_catalog.js' );
+    await startCatalog( { connection: mockConnection, namespace, catalog } );
+
+    expect( describeMock ).toHaveBeenCalled();
+    expect( executeUpdateMock ).toHaveBeenCalledWith( 'complete', { args: [] } );
+    expect( mockLog.warn ).toHaveBeenCalledWith( 'Error interacting with previous catalog workflow', {
+      error: expect.any( Error )
+    } );
+    expect( mockLog.info ).toHaveBeenCalledWith( 'Starting catalog workflow...' );
+    expect( workflowStartMock ).toHaveBeenCalledWith( 'catalog', {
+      taskQueue,
+      workflowId: catalogId,
+      workflowIdConflictPolicy: 'FAIL',
+      args: [ catalog ]
+    } );
+  } );
+} );

package/src/worker/webpack_loaders/tools.js

@@ -156,8 +156,13 @@ export const isAnyStepsPath = value =>
  * @param {string} value - Module path or request string.
  * @returns {boolean} True if it matches an evaluators path.
  */
-export const isEvaluatorsPath = value =>
-  EVALUATORS_FILE_REGEX.test( value ) || EVALUATORS_FOLDER_REGEX.test( value );
+export const isEvaluatorsPath = value => {
+  // Exclude shared evaluators (paths with ../ or containing /shared/)
+  if ( PATH_TRAVERSAL_REGEX.test( value ) || SHARED_PATH_REGEX.test( value ) ) {
+    return false;
+  }
+  return EVALUATORS_FILE_REGEX.test( value ) || EVALUATORS_FOLDER_REGEX.test( value );
+};
 
 /**
  * Check if a module specifier or request string points to shared evaluators.
@@ -174,6 +179,15 @@ export const isSharedEvaluatorsPath = value => {
   return PATH_TRAVERSAL_REGEX.test( value ) || SHARED_PATH_REGEX.test( value );
 };
 
+/**
+ * Check if a path matches any evaluators pattern (local or shared).
+ * Used for validation purposes.
+ * @param {string} value - Module path or request string.
+ * @returns {boolean} True if it matches any evaluators path pattern.
+ */
+export const isAnyEvaluatorsPath = value =>
+  EVALUATORS_FILE_REGEX.test( value ) || EVALUATORS_FOLDER_REGEX.test( value );
+
 /**
  * Check if a module specifier or request string points to workflow.js.
  * @param {string} value - Module path or request string.
@@ -187,7 +201,7 @@ export const isWorkflowPath = value => /(^|\/)workflow\.js$/.test( value );
  * @returns {boolean} True if it matches any component file path.
  */
 export const isComponentFile = value =>
-  isAnyStepsPath( value ) || isEvaluatorsPath( value ) || isWorkflowPath( value );
+  isAnyStepsPath( value ) || isAnyEvaluatorsPath( value ) || isWorkflowPath( value );
 
 /**
  * Determine file kind based on its path.
@@ -199,7 +213,7 @@ export const getFileKind = path => {
   if ( isAnyStepsPath( path ) ) {
     return ComponentFile.STEPS;
   }
-  if ( isEvaluatorsPath( path ) ) {
+  if ( isAnyEvaluatorsPath( path ) ) {
     return ComponentFile.EVALUATORS;
   }
   if ( isWorkflowPath( path ) ) {
@@ -357,6 +371,22 @@ export const buildEvaluatorsNameMap = ( path, cache ) => buildComponentNameMap(
   invalidMessagePrefix: 'Invalid evaluator name in'
 } );
 
+/**
+ * Build a map from exported shared evaluator identifier to declared evaluator name.
+ * Same as buildEvaluatorsNameMap but for shared evaluators.
+ *
+ * @param {string} path - Absolute path to the shared evaluators module file.
+ * @param {Map<string, Map<string,string>>} cache - Cache of computed evaluator name maps.
+ * @returns {Map<string,string>} Exported identifier -> evaluator name.
+ * @throws {Error} When an evaluator name is invalid (non-static or missing).
+ */
+export const buildSharedEvaluatorsNameMap = ( path, cache ) => buildComponentNameMap( {
+  path,
+  cache,
+  calleeName: 'evaluator',
+  invalidMessagePrefix: 'Invalid shared evaluator name in'
+} );
+
 /**
  * Build a structure with default and named workflow names from a workflow module.
  * Extracts names from `workflow({ name: '...' })` calls.

package/src/worker/webpack_loaders/tools.spec.js

@@ -190,11 +190,14 @@ describe( 'workflow_rewriter tools', () => {
     expect( isWorkflowPath( 'steps.js' ) ).toBe( false );
   } );
 
-  it( 'isEvaluatorsPath: matches evaluators.js at root or subpath', () => {
+  it( 'isEvaluatorsPath: matches local evaluators.js but excludes shared', () => {
     expect( isEvaluatorsPath( 'evaluators.js' ) ).toBe( true );
     expect( isEvaluatorsPath( './evaluators.js' ) ).toBe( true );
     expect( isEvaluatorsPath( '/a/b/evaluators.js' ) ).toBe( true );
     expect( isEvaluatorsPath( './evaluators/quality.js' ) ).toBe( true );
+    // Shared evaluators should NOT match (path traversal or /shared/)
+    expect( isEvaluatorsPath( '../evaluators.js' ) ).toBe( false );
+    expect( isEvaluatorsPath( '../../shared/evaluators/common.js' ) ).toBe( false );
     expect( isEvaluatorsPath( 'evaluators.ts' ) ).toBe( false );
     expect( isEvaluatorsPath( 'steps.js' ) ).toBe( false );
   } );

package/src/worker/webpack_loaders/workflow_rewriter/collect_target_imports.js

@@ -3,12 +3,14 @@ import {
   buildWorkflowNameMap,
   getLocalNameFromDestructuredProperty,
   isEvaluatorsPath,
+  isSharedEvaluatorsPath,
   isSharedStepsPath,
   isStepsPath,
   isWorkflowPath,
   buildStepsNameMap,
   buildSharedStepsNameMap,
   buildEvaluatorsNameMap,
+  buildSharedEvaluatorsNameMap,
   toAbsolutePath
 } from '../tools.js';
 import {
@@ -25,6 +27,46 @@ import {
 // Handle CJS/ESM interop for Babel packages when executed as a webpack loader
 const traverse = traverseModule.default ?? traverseModule;
 
+const unresolvedImportError = ( name, fileLabel, filePath ) =>
+  new Error(
+    `Unresolved import '${name}' from ${fileLabel} file '${filePath}'. ` +
+    'This export may have been defined with the wrong component type. ' +
+    'Use the matching factory function for the file ' +
+    '(e.g. step() in steps files, evaluator() in evaluators files, workflow() in workflow files).'
+  );
+
+const removeRequireDeclarator = path => {
+  if ( isVariableDeclaration( path.parent ) && path.parent.declarations.length === 1 ) {
+    path.parentPath.remove();
+  } else {
+    path.remove();
+  }
+};
+
+const collectDestructuredRequires = ( path, absolutePath, req, descriptors ) => {
+  const propFilter = p => isObjectProperty( p ) && isIdentifier( p.key );
+  for ( const { match, buildMap, cache, target, valueKey, label } of descriptors ) {
+    if ( !match( req ) ) {
+      continue;
+    }
+    const nameMap = buildMap( absolutePath, cache );
+    for ( const prop of path.node.id.properties.filter( propFilter ) ) {
+      const importedName = prop.key.name;
+      const localName = getLocalNameFromDestructuredProperty( prop );
+      if ( localName ) {
+        const resolved = nameMap.get( importedName );
+        if ( resolved ) {
+          target.push( { localName, [valueKey]: resolved } );
+        } else {
+          throw unresolvedImportError( importedName, label, absolutePath );
+        }
+      }
+    }
+    removeRequireDeclarator( path );
+    return;
+  }
+};
+
 /**
  * Collect and strip target imports and requires from an AST, producing
  * step/workflow import mappings for later rewrites.
@@ -38,22 +80,28 @@ const traverse = traverseModule.default ?? traverseModule;
  * @returns {{ stepImports: Array<{localName:string,stepName:string}>,
  *  flowImports: Array<{localName:string,workflowName:string}> }} Collected info mappings.
  */
-export default function collectTargetImports( ast, fileDir, { stepsNameCache, workflowNameCache, evaluatorsNameCache, sharedStepsNameCache } ) {
+export default function collectTargetImports(
+  ast, fileDir,
+  { stepsNameCache, workflowNameCache, evaluatorsNameCache, sharedStepsNameCache, sharedEvaluatorsNameCache }
+) {
   const stepImports = [];
   const sharedStepImports = [];
   const flowImports = [];
   const evaluatorImports = [];
+  const sharedEvaluatorImports = [];
 
   traverse( ast, {
     ImportDeclaration: path => {
       const src = path.node.source.value;
       // Ignore other imports
-      if ( !isStepsPath( src ) && !isSharedStepsPath( src ) && !isWorkflowPath( src ) && !isEvaluatorsPath( src ) ) {
+      const isTargetImport = isStepsPath( src ) || isSharedStepsPath( src ) ||
+        isWorkflowPath( src ) || isEvaluatorsPath( src ) || isSharedEvaluatorsPath( src );
+      if ( !isTargetImport ) {
         return;
       }
 
       const absolutePath = toAbsolutePath( fileDir, src );
-      const collectNamedImports = ( match, buildMapFn, cache, targetArr, valueKey ) => {
+      const collectNamedImports = ( match, buildMapFn, cache, targetArr, valueKey, fileLabel ) => {
         if ( !match ) {
           return;
         }
@@ -66,13 +114,19 @@ export default function collectTargetImports( ast, fileDir, { stepsNameCache, wo
             const entry = { localName };
             entry[valueKey] = value;
             targetArr.push( entry );
+          } else {
+            throw unresolvedImportError( importedName, fileLabel, absolutePath );
           }
         }
       };
 
-      collectNamedImports( isStepsPath( src ), buildStepsNameMap, stepsNameCache, stepImports, 'stepName' );
-      collectNamedImports( isSharedStepsPath( src ), buildSharedStepsNameMap, sharedStepsNameCache, sharedStepImports, 'stepName' );
-      collectNamedImports( isEvaluatorsPath( src ), buildEvaluatorsNameMap, evaluatorsNameCache, evaluatorImports, 'evaluatorName' );
+      collectNamedImports( isStepsPath( src ), buildStepsNameMap, stepsNameCache, stepImports, 'stepName', 'steps' );
+      collectNamedImports( isSharedStepsPath( src ), buildSharedStepsNameMap, sharedStepsNameCache, sharedStepImports, 'stepName', 'shared steps' );
+      collectNamedImports( isEvaluatorsPath( src ), buildEvaluatorsNameMap, evaluatorsNameCache, evaluatorImports, 'evaluatorName', 'evaluators' );
+      collectNamedImports(
+        isSharedEvaluatorsPath( src ), buildSharedEvaluatorsNameMap,
+        sharedEvaluatorsNameCache, sharedEvaluatorImports, 'evaluatorName', 'shared evaluators'
+      );
       if ( isWorkflowPath( src ) ) {
         const { named, default: defName } = buildWorkflowNameMap( absolutePath, workflowNameCache );
         for ( const s of path.node.specifiers ) {
@@ -85,6 +139,8 @@ export default function collectTargetImports( ast, fileDir, { stepsNameCache, wo
             const workflowName = named.get( importedName );
             if ( workflowName ) {
               flowImports.push( { localName, workflowName } );
+            } else {
+              throw unresolvedImportError( importedName, 'workflow', absolutePath );
             }
           }
         }
@@ -93,90 +149,73 @@ export default function collectTargetImports( ast, fileDir, { stepsNameCache, wo
     },
     VariableDeclarator: path => {
       const init = path.node.init;
-      // Not a require call
       if ( !isCallExpression( init ) ) {
         return;
       }
-      // Different callee
       if ( !isIdentifier( init.callee, { name: 'require' } ) ) {
         return;
       }
       const firstArgument = init.arguments[0];
-      // Dynamic require is not supported
       if ( !isStringLiteral( firstArgument ) ) {
         return;
       }
 
       const req = firstArgument.value;
-      // Must be steps/workflows module
-      if ( !isStepsPath( req ) && !isSharedStepsPath( req ) && !isWorkflowPath( req ) && !isEvaluatorsPath( req ) ) {
+      const isTargetRequire = isStepsPath( req ) || isSharedStepsPath( req ) ||
+        isWorkflowPath( req ) || isEvaluatorsPath( req ) || isSharedEvaluatorsPath( req );
+      if ( !isTargetRequire ) {
         return;
       }
 
       const absolutePath = toAbsolutePath( fileDir, req );
-      if ( isStepsPath( req ) && isObjectPattern( path.node.id ) ) {
-        const nameMap = buildStepsNameMap( absolutePath, stepsNameCache );
-        for ( const prop of path.node.id.properties.filter( prop => isObjectProperty( prop ) && isIdentifier( prop.key ) ) ) {
-          const importedName = prop.key.name;
-          const localName = getLocalNameFromDestructuredProperty( prop );
-          if ( localName ) {
-            const stepName = nameMap.get( importedName );
-            if ( stepName ) {
-              stepImports.push( { localName, stepName } );
-            }
-          }
-        }
-        if ( isVariableDeclaration( path.parent ) && path.parent.declarations.length === 1 ) {
-          path.parentPath.remove();
-        } else {
-          path.remove();
-        }
-      } else if ( isSharedStepsPath( req ) && isObjectPattern( path.node.id ) ) {
-        const nameMap = buildSharedStepsNameMap( absolutePath, sharedStepsNameCache ?? stepsNameCache );
-        for ( const prop of path.node.id.properties.filter( prop => isObjectProperty( prop ) && isIdentifier( prop.key ) ) ) {
-          const importedName = prop.key.name;
-          const localName = getLocalNameFromDestructuredProperty( prop );
-          if ( localName ) {
-            const stepName = nameMap.get( importedName );
-            if ( stepName ) {
-              sharedStepImports.push( { localName, stepName } );
-            }
-          }
-        }
-        if ( isVariableDeclaration( path.parent ) && path.parent.declarations.length === 1 ) {
-          path.parentPath.remove();
-        } else {
-          path.remove();
-        }
-      } else if ( isEvaluatorsPath( req ) && isObjectPattern( path.node.id ) ) {
-        const nameMap = buildEvaluatorsNameMap( absolutePath, evaluatorsNameCache );
-        for ( const prop of path.node.id.properties.filter( prop => isObjectProperty( prop ) && isIdentifier( prop.key ) ) ) {
-          const importedName = prop.key.name;
-          const localName = getLocalNameFromDestructuredProperty( prop );
-          if ( localName ) {
-            const evaluatorName = nameMap.get( importedName );
-            if ( evaluatorName ) {
-              evaluatorImports.push( { localName, evaluatorName } );
-            }
+
+      // Destructured requires: const { X } = require('./steps.js')
+      if ( isObjectPattern( path.node.id ) ) {
+        const cjsDescriptors = [
+          {
+            match: isStepsPath, buildMap: buildStepsNameMap,
+            cache: stepsNameCache, target: stepImports,
+            valueKey: 'stepName', label: 'steps'
+          },
+          {
+            match: isSharedStepsPath, buildMap: buildSharedStepsNameMap,
+            cache: sharedStepsNameCache ?? stepsNameCache,
+            target: sharedStepImports,
+            valueKey: 'stepName', label: 'shared steps'
+          },
+          {
+            match: isEvaluatorsPath, buildMap: buildEvaluatorsNameMap,
+            cache: evaluatorsNameCache, target: evaluatorImports,
+            valueKey: 'evaluatorName', label: 'evaluators'
+          },
+          {
+            match: isSharedEvaluatorsPath, buildMap: buildSharedEvaluatorsNameMap,
+            cache: sharedEvaluatorsNameCache ?? evaluatorsNameCache,
+            target: sharedEvaluatorImports,
+            valueKey: 'evaluatorName', label: 'shared evaluators'
+          },
+          {
+            match: isWorkflowPath,
+            buildMap: ( p, c ) => buildWorkflowNameMap( p, c ).named,
+            cache: workflowNameCache, target: flowImports,
+            valueKey: 'workflowName', label: 'workflow'
           }
-        }
-        if ( isVariableDeclaration( path.parent ) && path.parent.declarations.length === 1 ) {
-          path.parentPath.remove();
-        } else {
-          path.remove();
-        }
-      } else if ( isWorkflowPath( req ) && isIdentifier( path.node.id ) ) {
+        ];
+        collectDestructuredRequires(
+          path, absolutePath, req, cjsDescriptors
+        );
+        return;
+      }
+
+      // Default workflow require: const WF = require('./workflow.js')
+      if ( isWorkflowPath( req ) && isIdentifier( path.node.id ) ) {
         const { default: defName } = buildWorkflowNameMap( absolutePath, workflowNameCache );
         const localName = path.node.id.name;
         flowImports.push( { localName, workflowName: defName ?? localName } );
-        if ( isVariableDeclaration( path.parent ) && path.parent.declarations.length === 1 ) {
-          path.parentPath.remove();
-        } else {
-          path.remove();
-        }
+        removeRequireDeclarator( path );
       }
     }
   } );
 
-  return { stepImports, sharedStepImports, evaluatorImports, flowImports };
+  return { stepImports, sharedStepImports, evaluatorImports, sharedEvaluatorImports, flowImports };
 };

package/src/worker/webpack_loaders/workflow_rewriter/collect_target_imports.spec.js

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { mkdtempSync, writeFileSync, rmSync } from 'node:fs';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { parse } from '../tools.js';
@@ -75,5 +75,255 @@ const obj = {};`;
 
     rmSync( dir, { recursive: true, force: true } );
   } );
+
+  it( 'throws when ESM import from evaluators.js uses step() instead of evaluator()', () => {
+    const dir = mkdtempSync( join( tmpdir(), 'collect-esm-mismatch-eval-' ) );
+    writeFileSync( join( dir, 'evaluators.js' ), 'export const BadExport = step({ name: \'bad\' });' );
+
+    const source = 'import { BadExport } from \'./evaluators.js\';';
+    const ast = makeAst( source, join( dir, 'file.js' ) );
+
+    expect( () => collectTargetImports(
+      ast,
+      dir,
+      { stepsNameCache: new Map(), evaluatorsNameCache: new Map(), workflowNameCache: new Map() }
+    ) ).toThrow( /Unresolved import 'BadExport' from evaluators file/ );
+
+    rmSync( dir, { recursive: true, force: true } );
+  } );
+
+  it( 'throws when ESM import from steps.js uses evaluator() instead of step()', () => {
+    const dir = mkdtempSync( join( tmpdir(), 'collect-esm-mismatch-step-' ) );
+    writeFileSync( join( dir, 'steps.js' ), 'export const BadExport = evaluator({ name: \'bad\' });' );
+
+    const source = 'import { BadExport } from \'./steps.js\';';
+    const ast = makeAst( source, join( dir, 'file.js' ) );
+
+    expect( () => collectTargetImports(
+      ast,
+      dir,
+      { stepsNameCache: new Map(), evaluatorsNameCache: new Map(), workflowNameCache: new Map() }
+    ) ).toThrow( /Unresolved import 'BadExport' from steps file/ );
+
+    rmSync( dir, { recursive: true, force: true } );
+  } );
+
+  it( 'throws when CJS require from evaluators.js uses step() instead of evaluator()', () => {
+    const dir = mkdtempSync( join( tmpdir(), 'collect-cjs-mismatch-eval-' ) );
+    writeFileSync( join( dir, 'evaluators.js' ), 'export const BadExport = step({ name: \'bad\' });' );
+
+    const source = 'const { BadExport } = require( \'./evaluators.js\' );';
+    const ast = makeAst( source, join( dir, 'file.js' ) );
+
+    expect( () => collectTargetImports(
+      ast,
+      dir,
+      { stepsNameCache: new Map(), evaluatorsNameCache: new Map(), workflowNameCache: new Map() }
+    ) ).toThrow( /Unresolved import 'BadExport' from evaluators file/ );
+
+    rmSync( dir, { recursive: true, force: true } );
+  } );
+
+  it( 'throws when CJS require from steps.js uses evaluator() instead of step()', () => {
+    const dir = mkdtempSync( join( tmpdir(), 'collect-cjs-mismatch-step-' ) );
+    writeFileSync( join( dir, 'steps.js' ), 'export const BadExport = evaluator({ name: \'bad\' });' );
+
+    const source = 'const { BadExport } = require( \'./steps.js\' );';
+    const ast = makeAst( source, join( dir, 'file.js' ) );
+
+    expect( () => collectTargetImports(
+      ast,
+      dir,
+      { stepsNameCache: new Map(), evaluatorsNameCache: new Map(), workflowNameCache: new Map() }
+    ) ).toThrow( /Unresolved import 'BadExport' from steps file/ );
+
+    rmSync( dir, { recursive: true, force: true } );
+  } );
+
+  it( 'throws when ESM import from workflow.js has non-workflow export', () => {
+    const dir = mkdtempSync( join( tmpdir(), 'collect-esm-mismatch-wf-' ) );
+    writeFileSync( join( dir, 'workflow.js' ), 'export const helper = () => 42;' );
+
+    const source = 'import { helper } from \'./workflow.js\';';
+    const ast = makeAst( source, join( dir, 'file.js' ) );
+
+    expect( () => collectTargetImports(
+      ast,
+      dir,
+      { stepsNameCache: new Map(), evaluatorsNameCache: new Map(), workflowNameCache: new Map() }
+    ) ).toThrow( /Unresolved import 'helper' from workflow file/ );
+
+    rmSync( dir, { recursive: true, force: true } );
+  } );
+
+  it( 'throws when CJS destructured require from workflow.js has non-workflow export', () => {
+    const dir = mkdtempSync( join( tmpdir(), 'collect-cjs-mismatch-wf-' ) );
+    writeFileSync( join( dir, 'workflow.js' ), 'export const helper = () => 42;' );
+
+    const source = 'const { helper } = require( \'./workflow.js\' );';
+    const ast = makeAst( source, join( dir, 'file.js' ) );
+
+    expect( () => collectTargetImports(
+      ast,
+      dir,
+      { stepsNameCache: new Map(), evaluatorsNameCache: new Map(), workflowNameCache: new Map() }
+    ) ).toThrow( /Unresolved import 'helper' from workflow file/ );
+
+    rmSync( dir, { recursive: true, force: true } );
+  } );
+
+  it( 'collects CJS destructured require from workflow.js', () => {
+    const dir = mkdtempSync( join( tmpdir(), 'collect-cjs-wf-destruct-' ) );
+    writeFileSync( join( dir, 'workflow.js' ), 'export const FlowX = workflow({ name: \'flow.x\' });' );
+
+    const source = 'const { FlowX } = require( \'./workflow.js\' );\nconst obj = {};';
+    const ast = makeAst( source, join( dir, 'file.js' ) );
+
+    const { flowImports } = collectTargetImports(
+      ast,
+      dir,
+      { stepsNameCache: new Map(), evaluatorsNameCache: new Map(), workflowNameCache: new Map() }
+    );
+    expect( flowImports ).toEqual( [ { localName: 'FlowX', workflowName: 'flow.x' } ] );
+
+    rmSync( dir, { recursive: true, force: true } );
+  } );
+
+  it( 'collects ESM shared evaluator imports', () => {
+    const dir = mkdtempSync( join( tmpdir(), 'collect-esm-shared-eval-' ) );
+    mkdirSync( join( dir, 'shared', 'evaluators' ), { recursive: true } );
+    mkdirSync( join( dir, 'workflows', 'my_workflow' ), { recursive: true } );
+    writeFileSync(
+      join( dir, 'shared', 'evaluators', 'common.js' ),
+      'export const SharedEval = evaluator({ name: \'shared.eval\' });'
+    );
+
+    const source = 'import { SharedEval } from \'../../shared/evaluators/common.js\';';
+    const ast = makeAst( source, join( dir, 'workflows', 'my_workflow', 'workflow.js' ) );
+
+    const { sharedEvaluatorImports } = collectTargetImports(
+      ast,
+      join( dir, 'workflows', 'my_workflow' ),
+      { stepsNameCache: new Map(), evaluatorsNameCache: new Map(), sharedEvaluatorsNameCache: new Map(), workflowNameCache: new Map() }
+    );
+    expect( sharedEvaluatorImports ).toEqual( [ { localName: 'SharedEval', evaluatorName: 'shared.eval' } ] );
+
+    rmSync( dir, { recursive: true, force: true } );
+  } );
+
+  it( 'collects CJS shared evaluator requires', () => {
+    const dir = mkdtempSync( join( tmpdir(), 'collect-cjs-shared-eval-' ) );
+    mkdirSync( join( dir, 'shared', 'evaluators' ), { recursive: true } );
+    mkdirSync( join( dir, 'workflows', 'my_workflow' ), { recursive: true } );
+    writeFileSync(
+      join( dir, 'shared', 'evaluators', 'common.js' ),
+      'export const SharedEval = evaluator({ name: \'shared.eval\' });'
+    );
+
+    const source = 'const { SharedEval } = require( \'../../shared/evaluators/common.js\' );';
+    const ast = makeAst( source, join( dir, 'workflows', 'my_workflow', 'workflow.js' ) );
+
+    const { sharedEvaluatorImports } = collectTargetImports(
+      ast,
+      join( dir, 'workflows', 'my_workflow' ),
+      { stepsNameCache: new Map(), evaluatorsNameCache: new Map(), sharedEvaluatorsNameCache: new Map(), workflowNameCache: new Map() }
+    );
+    expect( sharedEvaluatorImports ).toEqual( [ { localName: 'SharedEval', evaluatorName: 'shared.eval' } ] );
+
+    rmSync( dir, { recursive: true, force: true } );
+  } );
+
+  it( 'collects CJS shared steps requires', () => {
+    const dir = mkdtempSync( join( tmpdir(), 'collect-cjs-shared-step-' ) );
+    mkdirSync( join( dir, 'shared', 'steps' ), { recursive: true } );
+    mkdirSync( join( dir, 'workflows', 'my_workflow' ), { recursive: true } );
+    writeFileSync(
+      join( dir, 'shared', 'steps', 'common.js' ),
+      'export const SharedA = step({ name: \'shared.a\' });'
+    );
+
+    const source = 'const { SharedA } = require( \'../../shared/steps/common.js\' );';
+    const ast = makeAst( source, join( dir, 'workflows', 'my_workflow', 'workflow.js' ) );
+
+    const { sharedStepImports } = collectTargetImports(
+      ast,
+      join( dir, 'workflows', 'my_workflow' ),
+      {
+        stepsNameCache: new Map(), sharedStepsNameCache: new Map(),
+        evaluatorsNameCache: new Map(), sharedEvaluatorsNameCache: new Map(),
+        workflowNameCache: new Map()
+      }
+    );
+    expect( sharedStepImports ).toEqual( [ { localName: 'SharedA', stepName: 'shared.a' } ] );
+
+    rmSync( dir, { recursive: true, force: true } );
+  } );
+
+  it( 'throws when CJS shared steps require uses evaluator() instead of step()', () => {
+    const dir = mkdtempSync( join( tmpdir(), 'collect-cjs-shared-step-mismatch-' ) );
+    mkdirSync( join( dir, 'shared', 'steps' ), { recursive: true } );
+    mkdirSync( join( dir, 'workflows', 'my_workflow' ), { recursive: true } );
+    writeFileSync(
+      join( dir, 'shared', 'steps', 'common.js' ),
+      'export const BadExport = evaluator({ name: \'bad\' });'
+    );
+
+    const source = 'const { BadExport } = require( \'../../shared/steps/common.js\' );';
+    const ast = makeAst( source, join( dir, 'workflows', 'my_workflow', 'workflow.js' ) );
+
+    expect( () => collectTargetImports(
+      ast,
+      join( dir, 'workflows', 'my_workflow' ),
+      {
+        stepsNameCache: new Map(), sharedStepsNameCache: new Map(),
+        evaluatorsNameCache: new Map(), sharedEvaluatorsNameCache: new Map(),
+        workflowNameCache: new Map()
+      }
+    ) ).toThrow( /Unresolved import 'BadExport' from shared steps file/ );
+
+    rmSync( dir, { recursive: true, force: true } );
+  } );
+
+  it( 'throws when CJS shared evaluator require uses step() instead of evaluator()', () => {
+    const dir = mkdtempSync( join( tmpdir(), 'collect-cjs-shared-eval-mismatch-' ) );
+    mkdirSync( join( dir, 'shared', 'evaluators' ), { recursive: true } );
+    mkdirSync( join( dir, 'workflows', 'my_workflow' ), { recursive: true } );
+    writeFileSync(
+      join( dir, 'shared', 'evaluators', 'common.js' ),
+      'export const BadExport = step({ name: \'bad\' });'
+    );
+
+    const source = 'const { BadExport } = require( \'../../shared/evaluators/common.js\' );';
+    const ast = makeAst( source, join( dir, 'workflows', 'my_workflow', 'workflow.js' ) );
+
+    expect( () => collectTargetImports(
+      ast,
+      join( dir, 'workflows', 'my_workflow' ),
+      { stepsNameCache: new Map(), evaluatorsNameCache: new Map(), sharedEvaluatorsNameCache: new Map(), workflowNameCache: new Map() }
+    ) ).toThrow( /Unresolved import 'BadExport' from shared evaluators file/ );
+
+    rmSync( dir, { recursive: true, force: true } );
+  } );
+
+  it( 'throws when ESM shared evaluator import uses step() instead of evaluator()', () => {
+    const dir = mkdtempSync( join( tmpdir(), 'collect-esm-shared-eval-mismatch-' ) );
+    mkdirSync( join( dir, 'shared', 'evaluators' ), { recursive: true } );
+    mkdirSync( join( dir, 'workflows', 'my_workflow' ), { recursive: true } );
+    writeFileSync(
+      join( dir, 'shared', 'evaluators', 'common.js' ),
+      'export const BadExport = step({ name: \'bad\' });'
+    );
+
+    const source = 'import { BadExport } from \'../../shared/evaluators/common.js\';';
+    const ast = makeAst( source, join( dir, 'workflows', 'my_workflow', 'workflow.js' ) );
+
+    expect( () => collectTargetImports(
+      ast,
+      join( dir, 'workflows', 'my_workflow' ),
+      { stepsNameCache: new Map(), evaluatorsNameCache: new Map(), sharedEvaluatorsNameCache: new Map(), workflowNameCache: new Map() }
+    ) ).toThrow( /Unresolved import 'BadExport' from shared evaluators file/ );
+
+    rmSync( dir, { recursive: true, force: true } );
+  } );
 } );
 

package/src/worker/webpack_loaders/workflow_rewriter/index.mjs

@@ -12,6 +12,7 @@ const generate = generatorModule.default ?? generatorModule;
 const stepsNameCache = new Map(); // path -> Map<exported, stepName>
 const sharedStepsNameCache = new Map(); // path -> Map<exported, stepName> (shared)
 const evaluatorsNameCache = new Map(); // path -> Map<exported, evaluatorName>
+const sharedEvaluatorsNameCache = new Map(); // path -> Map<exported, evaluatorName> (shared)
 const workflowNameCache = new Map(); // path -> { default?: name, named: Map<exported, flowName> }
 
 /**
@@ -27,20 +28,20 @@ const workflowNameCache = new Map(); // path -> { default?: name, named: Map<exp
 export default function stepImportRewriterAstLoader( source, inputMap ) {
   this.cacheable?.( true );
   const callback = this.async?.() ?? this.callback;
-  const cache = { stepsNameCache, sharedStepsNameCache, evaluatorsNameCache, workflowNameCache };
+  const cache = { stepsNameCache, sharedStepsNameCache, evaluatorsNameCache, sharedEvaluatorsNameCache, workflowNameCache };
 
   try {
     const filename = this.resourcePath;
     const ast = parse( String( source ), filename );
     const fileDir = dirname( filename );
-    const { stepImports, sharedStepImports, evaluatorImports, flowImports } = collectTargetImports( ast, fileDir, cache );
+    const { stepImports, sharedStepImports, evaluatorImports, sharedEvaluatorImports, flowImports } = collectTargetImports( ast, fileDir, cache );
 
     // No imports
-    if ( [].concat( stepImports, sharedStepImports, evaluatorImports, flowImports ).length === 0 ) {
+    if ( [].concat( stepImports, sharedStepImports, evaluatorImports, sharedEvaluatorImports, flowImports ).length === 0 ) {
       return callback( null, source, inputMap );
     }
 
-    const rewrote = rewriteFnBodies( { ast, stepImports, sharedStepImports, evaluatorImports, flowImports } );
+    const rewrote = rewriteFnBodies( { ast, stepImports, sharedStepImports, evaluatorImports, sharedEvaluatorImports, flowImports } );
     // No edits performed
     if ( !rewrote ) {
       return callback( null, source, inputMap );

package/src/worker/webpack_loaders/workflow_rewriter/index.spec.js

@@ -148,6 +148,54 @@ const obj = { fn: async () => { StepC(); FlowC(); FlowDef(); } }`;
     rmSync( dir, { recursive: true, force: true } );
   } );
 
+  it( 'rewrites ESM shared evaluator imports to invokeSharedEvaluator', async () => {
+    const dir = mkdtempSync( join( tmpdir(), 'ast-loader-esm-shared-eval-' ) );
+    mkdirSync( join( dir, 'shared', 'evaluators' ), { recursive: true } );
+    mkdirSync( join( dir, 'workflows', 'my_workflow' ), { recursive: true } );
+    writeFileSync( join( dir, 'shared', 'evaluators', 'common.js' ), 'export const SharedEval = evaluator({ name: \'shared.eval\' });' );
+
+    const source = `
+import { SharedEval } from '../../shared/evaluators/common.js';
+
+const obj = {
+  fn: async (x) => {
+    SharedEval(1);
+  }
+}`;
+
+    const { code } = await runLoader( source, join( dir, 'workflows', 'my_workflow', 'workflow.js' ) );
+
+    expect( code ).not.toMatch( /from '\.\.\/\.\.\/shared\/evaluators\/common\.js'/ );
+    expect( code ).toMatch( /fn:\s*async function \(x\)/ );
+    expect( code ).toMatch( /this\.invokeSharedEvaluator\('shared\.eval',\s*1\)/ );
+
+    rmSync( dir, { recursive: true, force: true } );
+  } );
+
+  it( 'rewrites CJS shared evaluator requires to invokeSharedEvaluator', async () => {
+    const dir = mkdtempSync( join( tmpdir(), 'ast-loader-cjs-shared-eval-' ) );
+    mkdirSync( join( dir, 'shared', 'evaluators' ), { recursive: true } );
+    mkdirSync( join( dir, 'workflows', 'my_workflow' ), { recursive: true } );
+    writeFileSync( join( dir, 'shared', 'evaluators', 'common.js' ), 'export const SharedEval = evaluator({ name: \'shared.eval\' });' );
+
+    const source = `
+const { SharedEval } = require( '../../shared/evaluators/common.js' );
+
+const obj = {
+  fn: async (y) => {
+    SharedEval();
+  }
+}`;
+
+    const { code } = await runLoader( source, join( dir, 'workflows', 'my_workflow', 'workflow.js' ) );
+
+    expect( code ).not.toMatch( /require\('\.\.\/\.\.\/shared\/evaluators\/common\.js'\)/ );
+    expect( code ).toMatch( /fn:\s*async function \(y\)/ );
+    expect( code ).toMatch( /this\.invokeSharedEvaluator\('shared\.eval'\)/ );
+
+    rmSync( dir, { recursive: true, force: true } );
+  } );
+
   it( 'throws on non-static name', async () => {
     const dir = mkdtempSync( join( tmpdir(), 'ast-loader-error-' ) );
     writeFileSync( join( dir, 'steps.js' ), `

package/src/worker/webpack_loaders/workflow_rewriter/rewrite_fn_bodies.js

@@ -156,13 +156,14 @@ const processFunction = ( { name, bindingPath, state, descriptors, processedFns
  * @param {Array<{localName:string,workflowName:string}>} params.flowImports - Workflow imports.
  * @returns {boolean} True if the AST was modified; false otherwise.
  */
-export default function rewriteFnBodies( { ast, stepImports, sharedStepImports = [], evaluatorImports, flowImports } ) {
+export default function rewriteFnBodies( { ast, stepImports, sharedStepImports = [], evaluatorImports, sharedEvaluatorImports = [], flowImports } ) {
   const state = { rewrote: false };
   // Build rewrite descriptors once per traversal
   const descriptors = [
     { list: stepImports, method: 'invokeStep', key: 'stepName' },
     { list: sharedStepImports, method: 'invokeSharedStep', key: 'stepName' },
     { list: evaluatorImports, method: 'invokeEvaluator', key: 'evaluatorName' },
+    { list: sharedEvaluatorImports, method: 'invokeSharedEvaluator', key: 'evaluatorName' },
     { list: flowImports, method: 'startWorkflow', key: 'workflowName' }
   ];
   traverse( ast, {

package/src/worker/webpack_loaders/workflow_validator/index.mjs

@@ -1,6 +1,6 @@
 import traverseModule from '@babel/traverse';
 import { dirname } from 'node:path';
-import { parse, toAbsolutePath, getFileKind, isAnyStepsPath, isEvaluatorsPath, isWorkflowPath } from '../tools.js';
+import { parse, toAbsolutePath, getFileKind, isAnyStepsPath, isAnyEvaluatorsPath, isWorkflowPath } from '../tools.js';
 import { ComponentFile } from '../consts.js';
 import {
   isCallExpression,
@@ -27,7 +27,7 @@ const getFileKindLabel = filename => {
   if ( isAnyStepsPath( filename ) ) {
     return 'steps.js';
   }
-  if ( isEvaluatorsPath( filename ) ) {
+  if ( isAnyEvaluatorsPath( filename ) ) {
     return 'evaluators.js';
   }
   if ( /workflow\.js$/.test( filename ) ) {
@@ -48,7 +48,7 @@ const validateInstantiationLocation = ( calleeName, filename ) => {
   if ( calleeName === 'step' && !isAnyStepsPath( filename ) ) {
     throw new Error( `Invalid instantiation location: step() can only be called in files with 'steps' in the path. Found in: ${filename}` );
   }
-  if ( calleeName === 'evaluator' && !isEvaluatorsPath( filename ) ) {
+  if ( calleeName === 'evaluator' && !isAnyEvaluatorsPath( filename ) ) {
     throw new Error( `Invalid instantiation location: evaluator() can only be called in files with 'evaluators' in the path. Found in: ${filename}` );
   }
   if ( calleeName === 'workflow' && !isWorkflowPath( filename ) ) {

package/src/worker/webpack_loaders/workflow_validator/index.spec.js

@@ -565,6 +565,28 @@ describe( 'workflow_validator loader', () => {
       rmSync( dir, { recursive: true, force: true } );
     } );
 
+    it( 'step() called in evaluators.js is blocked by validator', async () => {
+      const dir = mkdtempSync( join( tmpdir(), 'step-evals-fail-' ) );
+      const src = [
+        'import { step } from "@output.ai/core";',
+        'export const badStep = step({ name: "bad", fn: async () => ({}) });'
+      ].join( '\n' );
+      await expect( runLoader( join( dir, 'evaluators.js' ), src ) )
+        .rejects.toThrow( /Invalid instantiation location.*step\(\).*steps/ );
+      rmSync( dir, { recursive: true, force: true } );
+    } );
+
+    it( 'evaluator() called in steps.js is blocked by validator', async () => {
+      const dir = mkdtempSync( join( tmpdir(), 'eval-steps-fail-' ) );
+      const src = [
+        'import { evaluator } from "@output.ai/core";',
+        'export const badEval = evaluator({ name: "bad", fn: async () => ({ value: 1 }) });'
+      ].join( '\n' );
+      await expect( runLoader( join( dir, 'steps.js' ), src ) )
+        .rejects.toThrow( /Invalid instantiation location.*evaluator\(\).*evaluators/ );
+      rmSync( dir, { recursive: true, force: true } );
+    } );
+
     it( 'workflow() called in shared/common.js is blocked by validator', async () => {
       const dir = mkdtempSync( join( tmpdir(), 'wf-shared-fail-' ) );
       mkdirSync( join( dir, 'shared' ) );