@output.ai/core 0.5.2 → 0.5.4

package/package.json

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

package/src/consts.js

@@ -15,8 +15,3 @@ export const LifecycleEvent = {
   END: 'end',
   ERROR: 'error'
 };
-export const LifecycleEventLogMessage = {
-  [LifecycleEvent.START]: 'Start',
-  [LifecycleEvent.END]: 'End',
-  [LifecycleEvent.ERROR]: 'Error'
-};

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/activity.js

@@ -2,7 +2,7 @@ import { Context } from '@temporalio/activity';
 import { Storage } from '#async_storage';
 import { addEventStart, addEventEnd, addEventError } from '#tracing';
 import { headersToObject } from '../sandboxed_utils.js';
-import { LifecycleEventLogMessage, LifecycleEvent, METADATA_ACCESS_SYMBOL } from '#consts';
+import { LifecycleEvent, METADATA_ACCESS_SYMBOL } from '#consts';
 import { activityHeartbeatEnabled, activityHeartbeatIntervalMs } from '../configs.js';
 import { createChildLogger } from '#logger';
 
@@ -37,7 +37,7 @@ export class ActivityExecutionInterceptor {
     const logContext = { workflowName, workflowId, stepId: activityId, stepName: activityType };
     const traceArguments = { kind, id: activityId, parentId: workflowId, name: activityType, executionContext };
 
-    log.info( LifecycleEventLogMessage[LifecycleEvent.START], logContext );
+    log.info( `Started ${activityType} ${kind}`, { event: LifecycleEvent.START, kind, ...logContext } );
     addEventStart( { details: input.args[0], ...traceArguments } );
 
     const intervals = { heartbeat: null };
@@ -47,12 +47,14 @@ export class ActivityExecutionInterceptor {
 
       const output = await Storage.runWithContext( async _ => next( input ), { parentId: activityId, executionContext } );
 
-      log.info( LifecycleEventLogMessage[LifecycleEvent.END], { ...logContext, durationMs: Date.now() - startDate } );
+      log.info( `Ended ${activityType} ${kind}`, { event: LifecycleEvent.END, kind, ...logContext, durationMs: Date.now() - startDate } );
       addEventEnd( { details: output, ...traceArguments } );
       return output;
 
     } catch ( error ) {
-      log.error( LifecycleEventLogMessage[LifecycleEvent.ERROR], { ...logContext, durationMs: Date.now() - startDate, error: error.message } );
+      log.error( `Error ${activityType} ${kind}: ${error.message}`, {
+        event: LifecycleEvent.ERROR, kind, ...logContext, durationMs: Date.now() - startDate, error: error.message
+      } );
       addEventError( { details: error, ...traceArguments } );
       throw error;
 

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/sinks.js

@@ -1,4 +1,4 @@
-import { LifecycleEvent, LifecycleEventLogMessage, WORKFLOW_CATALOG } from '#consts';
+import { LifecycleEvent, WORKFLOW_CATALOG } from '#consts';
 import { addEventStart, addEventEnd, addEventError } from '#tracing';
 import { createChildLogger } from '#logger';
 
@@ -34,11 +34,12 @@ const logWorkflowEvent = ( event, workflowInfo, error ) => {
   }
 
   if ( event === LifecycleEvent.START ) {
-    log.info( LifecycleEventLogMessage[event], { workflowName, workflowId } );
+    log.info( `Started ${workflowName} workflow`, { event, workflowName, workflowId } );
   } else if ( event === LifecycleEvent.END ) {
-    log.info( LifecycleEventLogMessage[event], { workflowName, workflowId, durationMs: Date.now() - startTime.getTime() } );
+    log.info( `Ended ${workflowName} workflow`, { event, workflowName, workflowId, durationMs: Date.now() - startTime.getTime() } );
   } else if ( event === LifecycleEvent.ERROR ) {
-    log.info( LifecycleEventLogMessage[event], {
+    log.error( `Error ${workflowName} workflow: ${error.message}`, {
+      event,
       workflowName,
       workflowId,
       durationMs: Date.now() - startTime.getTime(),

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.