@outputai/core 0.7.1-next.de30052.0 → 0.8.0

package/src/worker/interceptors/activity.spec.js

@@ -1,12 +1,9 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-import { ACTIVITY_WRAPPER_VERSION_FIELD, BusEventType, Signal } from '#consts';
+import { ApplicationFailure } from '@temporalio/common';
+import { ACTIVITY_WRAPPER_VERSION_FIELD, BusEventType } from '#consts';
 import { Attribute } from '#trace_attribute';
 
 const METADATA_ACCESS_SYMBOL = vi.hoisted( () => Symbol( '__metadata' ) );
-const workflowHandleMock = vi.hoisted( () => ( { signal: vi.fn() } ) );
-const getHandleMock = vi.hoisted( () => vi.fn( () => workflowHandleMock ) );
-const clientConstructorMock = vi.hoisted( () => vi.fn() );
-const logWarnMock = vi.hoisted( () => vi.fn() );
 const heartbeatMock = vi.hoisted( () => vi.fn() );
 const runWithContextMock = vi.hoisted( () => vi.fn().mockImplementation( async fn => fn() ) );
 const activityInfoMock = vi.hoisted( () => ( {
@@ -32,27 +29,19 @@ const workflowDetailsMock = vi.hoisted( () => ( {
   attempt: 1
 } ) );
 
-vi.mock( '@temporalio/activity', () => ( {
-  activityInfo: () => activityInfoMock,
-  Context: {
-    current: () => ( {
-      info: activityInfoMock,
-      heartbeat: heartbeatMock
-    } )
-  }
-} ) );
-
-vi.mock( '@temporalio/client', () => ( {
-  Client: class Client {
-    constructor( options ) {
-      clientConstructorMock( options );
+vi.mock( '@temporalio/activity', async importOriginal => {
+  const actual = await importOriginal();
+  return {
+    ...actual,
+    activityInfo: () => activityInfoMock,
+    Context: {
+      current: () => ( {
+        info: activityInfoMock,
+        heartbeat: heartbeatMock
+      } )
     }
-
-    workflow = {
-      getHandle: getHandleMock
-    };
-  }
-} ) );
+  };
+} );
 
 vi.mock( '#async_storage', () => ( {
   Storage: {
@@ -60,10 +49,6 @@ vi.mock( '#async_storage', () => ( {
   }
 } ) );
 
-vi.mock( '#logger', () => ( {
-  createChildLogger: () => ( { warn: logWarnMock } )
-} ) );
-
 const addEventStartMock = vi.fn();
 const addEventEndMock = vi.fn();
 const addEventErrorMock = vi.fn();
@@ -95,9 +80,6 @@ vi.mock( '../configs.js', () => ( {
   },
   get activityHeartbeatIntervalMs() {
     return parseInt( process.env.OUTPUT_ACTIVITY_HEARTBEAT_INTERVAL_MS || '120000', 10 );
-  },
-  get namespace() {
-    return process.env.TEMPORAL_NAMESPACE || 'default';
   }
 } ) );
 
@@ -122,7 +104,6 @@ describe( 'ActivityExecutionInterceptor', () => {
   beforeEach( () => {
     vi.clearAllMocks();
     activityInfoMock.workflowType = 'myWorkflow';
-    workflowHandleMock.signal.mockResolvedValue( undefined );
     vi.useFakeTimers();
     vi.resetModules();
     // Default: heartbeat enabled with 50ms interval for fast tests
@@ -167,7 +148,6 @@ describe( 'ActivityExecutionInterceptor', () => {
     } );
     expect( addEventEndMock ).toHaveBeenCalledWith( { id: 'act-1', details: { result: 'ok' }, traceInfo: traceInfoMock } );
     expect( addEventErrorMock ).not.toHaveBeenCalled();
-    expect( clientConstructorMock ).not.toHaveBeenCalled();
     expect( runWithContextMock ).toHaveBeenCalledWith(
       expect.any( Function ),
       expect.objectContaining( {
@@ -180,7 +160,6 @@ describe( 'ActivityExecutionInterceptor', () => {
         addAttribute: expect.any( Function )
       } )
     );
-    expect( getHandleMock ).not.toHaveBeenCalled();
   } );
 
   it( 'handles next returning a non-Promise value', async () => {
@@ -199,7 +178,7 @@ describe( 'ActivityExecutionInterceptor', () => {
     expect( addEventErrorMock ).not.toHaveBeenCalled();
   } );
 
-  it( 'does not signal collected attributes after successful execution', async () => {
+  it( 'returns collected aggregations after successful execution', async () => {
     runWithContextMock.mockImplementationOnce( async ( fn, ctx ) => {
       ctx.addAttribute( httpRequestAttribute );
       return fn();
@@ -218,11 +197,9 @@ describe( 'ActivityExecutionInterceptor', () => {
       [ACTIVITY_WRAPPER_VERSION_FIELD]: 1
     } );
 
-    expect( workflowHandleMock.signal ).not.toHaveBeenCalled();
-    expect( clientConstructorMock ).not.toHaveBeenCalled();
   } );
 
-  it( 'signals collected aggregations after failed execution', async () => {
+  it( 'stores collected aggregations in ApplicationFailure details after failed execution', async () => {
     runWithContextMock.mockImplementationOnce( async ( fn, ctx ) => {
       ctx.addAttribute( httpRequestAttribute );
       return fn();
@@ -232,52 +209,106 @@ describe( 'ActivityExecutionInterceptor', () => {
     const error = new Error( 'step failed' );
     const next = vi.fn().mockRejectedValue( error );
 
-    await expect( interceptor.execute( makeInput(), next ) ).rejects.toThrow( 'step failed' );
-
-    expect( clientConstructorMock ).toHaveBeenCalledWith( { connection: undefined, namespace: 'default' } );
-    expect( getHandleMock ).toHaveBeenCalledWith( 'wf-1' );
-    expect( workflowHandleMock.signal ).toHaveBeenCalledWith( Signal.SEND_AGGREGATIONS, {
-      cost: { total: 0 },
-      tokens: { total: 0 },
-      httpRequests: { total: 1 }
+    const thrown = await interceptor.execute( makeInput(), next ).catch( e => e );
+    expect( thrown ).toBeInstanceOf( ApplicationFailure );
+    expect( thrown ).toMatchObject( {
+      message: 'step failed',
+      type: 'Error',
+      details: [ {
+        aggregations: {
+          cost: { total: 0 },
+          tokens: { total: 0 },
+          httpRequests: { total: 1 }
+        }
+      } ],
+      cause: error
     } );
     expect( messageBusEmitMock ).toHaveBeenCalledWith( BusEventType.ACTIVITY_ERROR, expect.objectContaining( { error } ) );
     expect( addEventErrorMock ).toHaveBeenCalledOnce();
     expect( addEventEndMock ).not.toHaveBeenCalled();
   } );
 
-  it( 'does not send fallback signal when failed execution collected no attributes', async () => {
+  it( 'appends collected aggregations to existing failure details', async () => {
+    runWithContextMock.mockImplementationOnce( async ( fn, ctx ) => {
+      ctx.addAttribute( httpRequestAttribute );
+      return fn();
+    } );
     const { ActivityExecutionInterceptor } = await import( './activity.js' );
     const interceptor = new ActivityExecutionInterceptor( { activities: makeActivities(), workflows: makeWorkflows() } );
-    const next = vi.fn().mockRejectedValue( new Error( 'step failed' ) );
+    const error = new Error( 'step failed' );
+    error.details = [ { domain: { reason: 'bad-input' } } ];
+    const next = vi.fn().mockRejectedValue( error );
+
+    const thrown = await interceptor.execute( makeInput(), next ).catch( e => e );
+
+    expect( thrown.details ).toEqual( [
+      { domain: { reason: 'bad-input' } },
+      {
+        aggregations: {
+          cost: { total: 0 },
+          tokens: { total: 0 },
+          httpRequests: { total: 1 }
+        }
+      }
+    ] );
+  } );
 
-    await expect( interceptor.execute( makeInput(), next ) ).rejects.toThrow( 'step failed' );
+  it( 'rethrows the original error when failed execution collected no attributes', async () => {
+    const { ActivityExecutionInterceptor } = await import( './activity.js' );
+    const interceptor = new ActivityExecutionInterceptor( { activities: makeActivities(), workflows: makeWorkflows() } );
+    const error = new Error( 'step failed' );
+    const next = vi.fn().mockRejectedValue( error );
 
-    expect( workflowHandleMock.signal ).not.toHaveBeenCalled();
-    expect( clientConstructorMock ).not.toHaveBeenCalled();
+    await expect( interceptor.execute( makeInput(), next ) ).rejects.toBe( error );
   } );
 
-  it( 'logs when fallback attribute signal fails', async () => {
-    const signalError = new Error( 'signal failed' );
-    workflowHandleMock.signal.mockRejectedValueOnce( signalError );
+  it( 'rethrows the original error with existing details when failed execution collected no attributes', async () => {
+    const { ActivityExecutionInterceptor } = await import( './activity.js' );
+    const interceptor = new ActivityExecutionInterceptor( { activities: makeActivities(), workflows: makeWorkflows() } );
+    const error = new Error( 'step failed' );
+    error.details = [ { domain: { reason: 'bad-input' } } ];
+    const next = vi.fn().mockRejectedValue( error );
+
+    await expect( interceptor.execute( makeInput(), next ) ).rejects.toBe( error );
+    expect( error.details ).toEqual( [ { domain: { reason: 'bad-input' } } ] );
+  } );
+
+  it( 'wraps existing ApplicationFailure without creating a self-cause', async () => {
     runWithContextMock.mockImplementationOnce( async ( fn, ctx ) => {
       ctx.addAttribute( httpRequestAttribute );
       return fn();
     } );
+    const error = ApplicationFailure.create( {
+      message: 'application failed',
+      type: 'OriginalType',
+      nonRetryable: true,
+      details: [ { domain: { reason: 'bad-input' } } ]
+    } );
     const { ActivityExecutionInterceptor } = await import( './activity.js' );
     const interceptor = new ActivityExecutionInterceptor( { activities: makeActivities(), workflows: makeWorkflows() } );
-    const next = vi.fn().mockRejectedValue( new Error( 'step failed' ) );
-
-    await expect( interceptor.execute( makeInput(), next ) ).rejects.toThrow( 'step failed' );
+    const next = vi.fn().mockRejectedValue( error );
 
-    expect( logWarnMock ).toHaveBeenCalledWith( `Signal "${Signal.SEND_AGGREGATIONS}" failed`, expect.objectContaining( {
-      message: 'signal failed',
-      activityId: 'act-1',
-      activityType: 'myWorkflow#myStep',
-      workflowId: 'wf-1',
-      workflowType: 'myWorkflow',
-      runId: 'run-1'
-    } ) );
+    const thrown = await interceptor.execute( makeInput(), next ).catch( e => e );
+
+    expect( thrown ).toBeInstanceOf( ApplicationFailure );
+    expect( thrown ).not.toBe( error );
+    expect( thrown.cause ).toBe( error );
+    expect( thrown.cause ).not.toBe( thrown );
+    expect( thrown ).toMatchObject( {
+      message: 'application failed',
+      type: 'OriginalType',
+      nonRetryable: true,
+      details: [
+        { domain: { reason: 'bad-input' } },
+        {
+          aggregations: {
+            cost: { total: 0 },
+            tokens: { total: 0 },
+            httpRequests: { total: 1 }
+          }
+        }
+      ]
+    } );
   } );
 
   it( 'records trace error event on failed execution', async () => {

package/src/worker/interceptors/index.js

@@ -1,14 +1,11 @@
-import { dirname, join } from 'path';
-import { fileURLToPath } from 'node:url';
 import { ActivityExecutionInterceptor } from './activity.js';
+import { workflowInterceptorModules } from './modules.js';
 
-const __dirname = dirname( fileURLToPath( import.meta.url ) );
-
-export const initInterceptors = ( { activities, workflows, connection } ) => ( {
-  workflowModules: [ join( __dirname, './workflow.js' ) ],
+export const initInterceptors = ( { activities, workflows } ) => ( {
+  workflowModules: workflowInterceptorModules,
   activity: [
     () => ( {
-      inbound: new ActivityExecutionInterceptor( { activities, workflows, connection } )
+      inbound: new ActivityExecutionInterceptor( { activities, workflows } )
     } )
   ]
 } );

package/src/worker/interceptors/modules.js

@@ -0,0 +1,15 @@
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname( fileURLToPath( import.meta.url ) );
+
+/**
+ * Workflow-side interceptor modules bundled into the workflow code.
+ *
+ * Kept in its own module — free of activity/config imports — so the bundle check
+ * (`bundleWorkflows`) can register the exact same modules as the worker without
+ * pulling in worker runtime config (e.g. the OUTPUT_CATALOG_ID env validation).
+ * This is the single source of truth shared by `initInterceptors` and the check,
+ * keeping `output-worker --check` in parity with `Worker.create`.
+ */
+export const workflowInterceptorModules = [ join( __dirname, './workflow.js' ) ];

package/src/worker/interceptors/workflow.js

@@ -1,11 +1,13 @@
 // THIS RUNS IN THE TEMPORAL'S SANDBOX ENVIRONMENT
-import { workflowInfo, proxySinks, ApplicationFailure, ContinueAsNew, isCancellation } from '@temporalio/workflow';
+import { workflowInfo, proxySinks, ContinueAsNew, isCancellation } from '@temporalio/workflow';
 import { memoToHeaders } from './headers.js';
 import { deepMerge } from '#utils';
+import { buildApplicationFailureWithDetails } from '#internal_utils/errors';
 import { METADATA_ACCESS_SYMBOL, WorkflowSpecialOutput } from '#consts';
+import { createWorkflowDetails } from '#internal_utils/temporal_context';
+
 // this is a dynamic generated file with activity configs overwrites
 import stepOptions from '../temp/__activity_options.js';
-import { createWorkflowDetails } from '#internal_utils/temporal_context';
 
 /*
   This interceptor adds Memo and serialized workflowInfo() to the Activity invocation headers.
@@ -55,17 +57,13 @@ class WorkflowExecutionInterceptor {
       }
 
       sinks.workflow.error( error );
-      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.
+       * Add internal error .details to Temporal's ApplicationFailure .details
        * This make it possible for this information be retrieved by Temporal's client instance.
        * Ref: https://typescript.temporal.io/api/classes/common.ApplicationFailure#details
        */
-      if ( error[METADATA_ACCESS_SYMBOL] ) {
-        failure.details = [ error[METADATA_ACCESS_SYMBOL] ];
-      }
-      throw failure;
+      throw error[METADATA_ACCESS_SYMBOL] ? buildApplicationFailureWithDetails( error, error[METADATA_ACCESS_SYMBOL] ) : error;
     }
   }
 };

package/src/worker/interceptors/workflow.spec.js

@@ -1,6 +1,6 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
-
-const METADATA_ACCESS_SYMBOL = vi.hoisted( () => Symbol( '__metadata' ) );
+import { ApplicationFailure } from '@temporalio/common';
+import { METADATA_ACCESS_SYMBOL } from '#consts';
 
 const workflowInfoMock = vi.fn();
 const workflowStartMock = vi.fn();
@@ -41,16 +41,6 @@ vi.mock( '@temporalio/workflow', () => ( {
   proxySinks: () => ( {
     workflow: { start: workflowStartMock, end: workflowEndMock, error: workflowErrorMock }
   } ),
-  ApplicationFailure: class ApplicationFailure {
-    constructor( message, type, nonRetryable, cause, originalError ) {
-      this.message = message;
-      this.type = type;
-      this.nonRetryable = nonRetryable;
-      this.cause = cause;
-      this.originalError = originalError;
-      this.details = undefined;
-    }
-  },
   ContinueAsNew: class ContinueAsNew extends Error {
     constructor() {
       super( 'ContinueAsNew' );
@@ -66,15 +56,6 @@ vi.mock( './headers.js', () => ( { memoToHeaders: ( ...args ) => memoToHeadersMo
 const deepMergeMock = vi.fn( ( a, b ) => ( { ...( a || {} ), ...( b || {} ) } ) );
 vi.mock( '#utils', () => ( { deepMerge: ( ...args ) => deepMergeMock( ...args ) } ) );
 
-vi.mock( '#consts', async importOriginal => {
-  const actual = await importOriginal();
-  return {
-    ...actual, get METADATA_ACCESS_SYMBOL() {
-      return METADATA_ACCESS_SYMBOL;
-    }
-  };
-} );
-
 const stepOptionsDefault = {};
 vi.mock( '../temp/__activity_options.js', () => ( { default: stepOptionsDefault } ) );
 
@@ -150,7 +131,7 @@ describe( 'workflow interceptors', () => {
       expect( workflowErrorMock ).not.toHaveBeenCalled();
     } );
 
-    it( 'calls sinks.workflow.error and throws ApplicationFailure on error', async () => {
+    it( 'calls sinks.workflow.error and rethrows workflow errors', async () => {
       const { interceptors } = await import( './workflow.js' );
       const { inbound } = interceptors();
       const interceptor = inbound[0];
@@ -158,41 +139,68 @@ describe( 'workflow interceptors', () => {
       const err = new Error( 'workflow failed' );
       const next = vi.fn().mockRejectedValue( err );
 
-      await expect( interceptor.execute( input, next ) ).rejects.toMatchObject( {
+      await expect( interceptor.execute( input, next ) ).rejects.toBe( err );
+      expect( workflowStartMock ).toHaveBeenCalled();
+      expect( workflowErrorMock ).toHaveBeenCalledWith( err );
+      expect( workflowEndMock ).not.toHaveBeenCalled();
+    } );
+
+    it( 'wraps workflow errors with metadata in ApplicationFailure details', async () => {
+      const { interceptors } = await import( './workflow.js' );
+      const { inbound } = interceptors();
+      const interceptor = inbound[0];
+      const trace = { trace: { destinations: { local: '/tmp/trace' } } };
+      const err = new Error( 'workflow failed' );
+      err[METADATA_ACCESS_SYMBOL] = trace;
+      const next = vi.fn().mockRejectedValue( err );
+
+      const thrown = await interceptor.execute( { args: [ {} ] }, next ).catch( e => e );
+
+      expect( thrown ).toBeInstanceOf( ApplicationFailure );
+      expect( thrown ).toMatchObject( {
         message: 'workflow failed',
         type: 'Error',
-        originalError: err
+        details: [ trace ],
+        cause: err
       } );
-      expect( workflowStartMock ).toHaveBeenCalled();
       expect( workflowErrorMock ).toHaveBeenCalledWith( err );
       expect( workflowEndMock ).not.toHaveBeenCalled();
     } );
 
-    it( 'sets failure.details from error metadata when present', async () => {
+    it( 'preserves ApplicationFailure metadata when wrapping workflow errors with details', async () => {
       const { interceptors } = await import( './workflow.js' );
-      const { ApplicationFailure } = await import( '@temporalio/workflow' );
       const { inbound } = interceptors();
       const interceptor = inbound[0];
-      const meta = { code: 'CUSTOM' };
-      const err = new Error( 'custom' );
-      err[METADATA_ACCESS_SYMBOL] = meta;
+      const trace = { trace: { destinations: { local: '/tmp/trace' } } };
+      const err = ApplicationFailure.create( {
+        message: 'domain failed',
+        type: 'DomainFailure',
+        nonRetryable: true,
+        details: [ { domain: { reason: 'bad-input' } } ]
+      } );
+      err[METADATA_ACCESS_SYMBOL] = trace;
       const next = vi.fn().mockRejectedValue( err );
 
-      const error = await ( async () => {
-        try {
-          await interceptor.execute( { args: [ {} ] }, next );
-          return null;
-        } catch ( error ) {
-          return error;
-        }
-      } )();
-      expect( error ).toBeInstanceOf( ApplicationFailure );
-      expect( error.details ).toEqual( [ meta ] );
+      const thrown = await interceptor.execute( { args: [ {} ] }, next ).catch( e => e );
+
+      expect( thrown ).toBeInstanceOf( ApplicationFailure );
+      expect( thrown ).not.toBe( err );
+      expect( thrown.cause ).toBe( err );
+      expect( thrown.cause ).not.toBe( thrown );
+      expect( thrown ).toMatchObject( {
+        message: 'domain failed',
+        type: 'DomainFailure',
+        nonRetryable: true,
+        details: [
+          { domain: { reason: 'bad-input' } },
+          trace
+        ]
+      } );
+      expect( workflowErrorMock ).toHaveBeenCalledWith( err );
     } );
 
     it( 'calls sinks.workflow.error and rethrows cancellation errors without wrapping', async () => {
       const { interceptors } = await import( './workflow.js' );
-      const { ApplicationFailure } = await import( '@temporalio/workflow' );
       const { inbound } = interceptors();
       const interceptor = inbound[0];
       const cancellation = new Error( 'Workflow cancelled' );
@@ -201,7 +209,6 @@ describe( 'workflow interceptors', () => {
 
       await expect( interceptor.execute( { args: [ {} ] }, next ) ).rejects.toBe( cancellation );
       expect( isCancellationMock ).toHaveBeenCalledWith( cancellation );
-      expect( cancellation ).not.toBeInstanceOf( ApplicationFailure );
       expect( workflowErrorMock ).toHaveBeenCalledWith( cancellation );
       expect( workflowEndMock ).not.toHaveBeenCalled();
     } );

package/src/worker/interruption.js

@@ -0,0 +1,33 @@
+import { createChildLogger } from '#logger';
+
+const log = createChildLogger( 'Interruption' );
+
+const FORCE_QUIT_GRACE_MS = 1000;
+const INTERRUPTION_SIGNALS = [ 'SIGTERM', 'SIGINT', 'SIGUSR2' ];
+
+export const setupInterruptionHandler = cb => {
+  const state = { interruptionReceivedAt: null };
+
+  const handle = signal => {
+    log.info( 'Signal Received', { signal } );
+
+    if ( state.interruptionReceivedAt ) {
+      const elapsed = Date.now() - state.interruptionReceivedAt;
+
+      // 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 );
+      return;
+    }
+
+    state.interruptionReceivedAt = Date.now();
+    log.warn( 'Initiating shutdown...' );
+    cb();
+  };
+
+  INTERRUPTION_SIGNALS.forEach( signal => process.on( signal, () => handle( signal ) ) );
+};

package/src/worker/interruption.spec.js

@@ -0,0 +1,98 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { setupInterruptionHandler } from './interruption.js';
+
+const { mockLog } = vi.hoisted( () => ( {
+  mockLog: { info: vi.fn(), warn: vi.fn() }
+} ) );
+
+vi.mock( '#logger', () => ( { createChildLogger: () => mockLog } ) );
+
+describe( 'setupInterruptionHandler', () => {
+  const onHandlers = {};
+  const callback = vi.fn();
+  const exitMock = vi.fn();
+  const originalOn = process.on;
+  const originalExit = process.exit;
+
+  beforeEach( () => {
+    vi.clearAllMocks();
+    Object.keys( onHandlers ).forEach( key => delete onHandlers[key] );
+    process.on = vi.fn( ( event, handler ) => {
+      onHandlers[event] = handler;
+    } );
+    process.exit = exitMock;
+  } );
+
+  afterEach( () => {
+    vi.useRealTimers();
+    process.on = originalOn;
+    process.exit = originalExit;
+  } );
+
+  it( 'registers interruption signal handlers', () => {
+    setupInterruptionHandler( callback );
+
+    expect( process.on ).toHaveBeenCalledWith( 'SIGTERM', expect.any( Function ) );
+    expect( process.on ).toHaveBeenCalledWith( 'SIGINT', expect.any( Function ) );
+    expect( process.on ).toHaveBeenCalledWith( 'SIGUSR2', expect.any( Function ) );
+  } );
+
+  it( 'logs and invokes callback on first SIGTERM', () => {
+    setupInterruptionHandler( callback );
+
+    onHandlers.SIGTERM();
+
+    expect( mockLog.info ).toHaveBeenCalledWith( 'Signal Received', { signal: 'SIGTERM' } );
+    expect( mockLog.warn ).toHaveBeenCalledWith( 'Initiating shutdown...' );
+    expect( callback ).toHaveBeenCalledOnce();
+    expect( exitMock ).not.toHaveBeenCalled();
+  } );
+
+  it( 'logs and invokes callback on first SIGINT', () => {
+    setupInterruptionHandler( callback );
+
+    onHandlers.SIGINT();
+
+    expect( mockLog.info ).toHaveBeenCalledWith( 'Signal Received', { signal: 'SIGINT' } );
+    expect( mockLog.warn ).toHaveBeenCalledWith( 'Initiating shutdown...' );
+    expect( callback ).toHaveBeenCalledOnce();
+    expect( exitMock ).not.toHaveBeenCalled();
+  } );
+
+  it( 'logs and invokes callback on first SIGUSR2', () => {
+    setupInterruptionHandler( callback );
+
+    onHandlers.SIGUSR2();
+
+    expect( mockLog.info ).toHaveBeenCalledWith( 'Signal Received', { signal: 'SIGUSR2' } );
+    expect( mockLog.warn ).toHaveBeenCalledWith( 'Initiating shutdown...' );
+    expect( callback ).toHaveBeenCalledOnce();
+    expect( exitMock ).not.toHaveBeenCalled();
+  } );
+
+  it( 'ignores a second signal received within the grace period', () => {
+    vi.useFakeTimers();
+    setupInterruptionHandler( callback );
+
+    onHandlers.SIGTERM();
+    onHandlers.SIGINT();
+
+    expect( callback ).toHaveBeenCalledOnce();
+    expect( mockLog.warn ).toHaveBeenCalledTimes( 1 );
+    expect( mockLog.warn ).toHaveBeenCalledWith( 'Initiating shutdown...' );
+    expect( exitMock ).not.toHaveBeenCalled();
+  } );
+
+  it( 'force quits on a second signal after the grace period', () => {
+    vi.useFakeTimers();
+    setupInterruptionHandler( callback );
+
+    onHandlers.SIGTERM();
+    vi.advanceTimersByTime( 1001 );
+    onHandlers.SIGINT();
+
+    expect( callback ).toHaveBeenCalledOnce();
+    expect( mockLog.warn ).toHaveBeenCalledWith( 'Force quitting...' );
+    expect( exitMock ).toHaveBeenCalledWith( 1 );
+  } );
+} );