lifecycleion 0.0.13 → 0.0.14

package/dist/lib/lifecycle-manager/index.d.cts

@@ -158,7 +158,7 @@ interface RestartComponentOptions {
 /**
  * Stable, machine-readable failure codes for individual component operations
  */
-type ComponentOperationFailureCode = 'component_not_found' | 'component_already_running' | 'component_already_starting' | 'component_already_stopping' | 'component_not_running' | 'component_stalled' | 'missing_dependency' | 'dependency_not_running' | 'has_running_dependents' | 'startup_in_progress' | 'shutdown_in_progress' | 'component_startup_timeout' | 'component_shutdown_timeout' | 'restart_stop_failed' | 'restart_start_failed' | 'unknown_error';
+type ComponentOperationFailureCode = 'component_not_found' | 'component_already_running' | 'component_already_starting' | 'component_already_stopping' | 'component_not_running' | 'component_stalled' | 'missing_dependency' | 'dependency_not_running' | 'has_running_dependents' | 'startup_in_progress' | 'shutdown_in_progress' | 'component_unexpected_stop' | 'component_startup_timeout' | 'component_shutdown_timeout' | 'restart_stop_failed' | 'restart_start_failed' | 'unknown_error';
 /**
  * Failure codes for unregister operations
  */
@@ -202,7 +202,7 @@ interface StartupResult {
     /** Reason for failure (when success is false) */
     reason?: string;
     /** Error code (when success is false) */
-    code?: 'already_in_progress' | 'shutdown_in_progress' | 'dependency_cycle' | 'no_components_registered' | 'stalled_components_exist' | 'partial_state' | 'required_component_failed' | 'startup_timeout' | 'unknown_error';
+    code?: 'already_in_progress' | 'component_unexpected_stop' | 'shutdown_in_progress' | 'dependency_cycle' | 'no_components_registered' | 'stalled_components_exist' | 'partial_state' | 'required_component_failed' | 'startup_timeout' | 'unknown_error';
     /** Error object (when success is false due to dependency cycle or unknown error) */
     error?: Error;
     /** Total startup duration in milliseconds */
@@ -956,6 +956,10 @@ declare abstract class BaseComponent {
     protected name: string;
     /** Reference to component-scoped lifecycle (set by manager when registered) */
     protected lifecycle: ComponentLifecycleRef;
+    /** @internal Set by LifecycleManager while the component is running. */
+    private _unexpectedStopHandler?;
+    /** @internal Incremented whenever the unexpected-stop handler is re-armed or cleared. */
+    private _unexpectedStopGeneration;
     /**
      * Create a new component
      *
@@ -964,6 +968,10 @@ declare abstract class BaseComponent {
      * @throws {InvalidComponentNameError} If name doesn't match kebab-case pattern
      */
     constructor(rootLogger: Logger, options: ComponentOptions);
+    /** @internal Called by LifecycleManager after a successful start. */
+    _setUnexpectedStopHandler(handler: (error?: Error) => boolean): void;
+    /** @internal Called by LifecycleManager when stop begins or component is unregistered. */
+    _clearUnexpectedStopHandler(): void;
     /**
      * Start the component
      *
@@ -1146,6 +1154,28 @@ declare abstract class BaseComponent {
      * Check if component is optional
      */
     isOptional(): boolean;
+    /**
+     * Run-scoped unexpected-stop callback. Rebound by LifecycleManager on each
+     * successful start so captured references from older runs go stale.
+     */
+    protected reportUnexpectedStop: (error?: Error) => boolean;
+    /**
+     * Get this component's own status from the manager's perspective.
+     *
+     * Equivalent to `this.lifecycle.getComponentStatus(this.getName())` but without
+     * needing to pass the name. Returns `undefined` if the component is not registered.
+     *
+     * Check `status?.state === 'running'` to test whether the component is currently running.
+     */
+    protected getSelfStatus(): ComponentStatus | undefined;
+    /**
+     * Capture a run-scoped unexpected-stop reporter for async listeners created during start().
+     *
+     * Unlike calling `this.reportUnexpectedStop()` later, the returned callback becomes a no-op
+     * once the component is stopped, unregistered, or restarted. This prevents stale listeners
+     * from a previous run from stopping a newer run of the same component instance.
+     */
+    protected getUnexpectedStopReporter(): (error?: Error) => boolean;
 }
 
 /**
@@ -1179,7 +1209,11 @@ declare class LifecycleManager extends EventEmitterProtected implements Lifecycl
     private componentTimestamps;
     private componentErrors;
     private componentStartAttemptTokens;
+    private componentStopAttemptTokens;
+    private pendingForceStopWaiters;
+    private unexpectedStopsDuringStartup;
     private isStarting;
+    private autoAttachedSignalsDuringStartup;
     private isStarted;
     private isShuttingDown;
     private shutdownToken;
@@ -1592,6 +1626,45 @@ declare class LifecycleManager extends EventEmitterProtected implements Lifecycl
     private autoAttachSignals;
     private autoDetachSignalsIfIdle;
     private monitorLateStartupCompletion;
+    private consumeUnexpectedStopsDuringStartup;
+    /**
+     * Issues and returns a unique stop attempt token for a component.
+     *
+     * Each stop attempt (graceful or force-retry) gets a unique token.
+     * The late-resolution handler captures this token in its closure so it can
+     * skip any stall entries that were created by a *later* stop attempt — e.g. a
+     * force-retry that also timed out after the original graceful promise floated
+     * in the background.
+     */
+    private issueStopAttemptToken;
+    private createPendingForceStopWaiter;
+    private resolvePendingForceStopWaiters;
+    /**
+     * Called when a stop promise eventually resolves after its timeout path already fired.
+     *
+     * Usually this means a previously stalled component's original stop() or
+     * onShutdownForce() promise finally resolved, so the manager can clear the
+     * stall and transition the component to stopped without a manual retry.
+     *
+     * There is one extra overlap case for graceful stop(): stop() can resolve
+     * after the graceful timeout but before onShutdownForce() itself times out.
+     * In that window no stall entry exists yet, but the component still finished
+     * stopping cleanly, so we finalize it here and let the later force-timeout
+     * path observe the already-stopped state and no-op. This overlap fix is
+     * scoped to the same stop token and will not cross a later retry attempt.
+     *
+     * Two guards prevent stale floating promises from incorrectly clearing state:
+     *
+     * 1. token guard — if a newer stop attempt (e.g. a retryStalled
+     *    force-retry) has started since this promise was launched, its token
+     *    won't match and we bail out immediately.
+     *
+     * 2. state/stall guard — if the component was unregistered, restarted, or
+     *    already cleared by another path, there will be neither a matching stall
+     *    entry nor the force-phase overlap state, so we bail out.
+     */
+    private handleLateStopResolution;
+    private handleComponentUnexpectedStop;
     /**
      * Safe emit wrapper - prevents event handler errors from breaking lifecycle
      */
@@ -1713,36 +1786,27 @@ declare class LifecycleManager extends EventEmitterProtected implements Lifecycl
      */
     private armRepeatedShutdownAfterFailure;
     /**
-     * Handle reload request - calls custom callback or broadcasts to components.
+     * Shared dispatch path for reload/info/debug requests. Logs the dispatch,
+     * emits the signal event, then either invokes the user-supplied callback
+     * (passing the broadcast function so the user controls when/whether to
+     * broadcast) or broadcasts directly when no callback is configured.
      *
      * When called from signal handlers (source='signal'), the Promise is started
-     * but not awaited due to Node.js signal handler constraints. Components are
-     * still notified and the work completes, but return values are not accessible.
-     *
+     * but not awaited — Node.js signal handlers cannot return values, so results
+     * are not accessible. Components are still notified and the work completes.
      * When called from manual triggers (source='trigger'), the Promise is awaited
      * and results are returned for programmatic use.
-     *
-     * @param source - Whether triggered from signal manager or manual trigger
      */
+    private handleSignalRequest;
     private handleReloadRequest;
-    /**
-     * Handle info request - calls custom callback or broadcasts to components.
-     *
-     * When called from signal handlers, the Promise executes but return values
-     * are not accessible due to Node.js signal handler constraints.
-     *
-     * @param source - Whether triggered from signal manager or manual trigger
-     */
     private handleInfoRequest;
+    private handleDebugRequest;
     /**
-     * Handle debug request - calls custom callback or broadcasts to components.
-     *
-     * When called from signal handlers, the Promise executes but return values
-     * are not accessible due to Node.js signal handler constraints.
-     *
-     * @param source - Whether triggered from signal manager or manual trigger
+     * Shared signal broadcast pipeline used by reload/info/debug.
+     * Iterates running components, runs the picked handler with timeout, and
+     * aggregates per-component results into a SignalBroadcastResult.
      */
-    private handleDebugRequest;
+    private runSignalBroadcast;
     /**
      * Broadcast reload signal to all running components.
      * Calls onReload() on components that implement it.
@@ -1962,6 +2026,15 @@ interface LifecycleManagerEventMap {
         reason?: string;
         code?: string;
     };
+    'component:stalled-resolved': {
+        name: string;
+        stallInfo: ComponentStallInfo;
+        stalledDurationMS: number;
+    };
+    'component:unexpected-stop': {
+        name: string;
+        error?: Error;
+    };
     'component:shutdown-force-completed': {
         name: string;
     };
@@ -2140,6 +2213,8 @@ declare class LifecycleManagerEvents {
         reason?: string;
         code?: string;
     }): void;
+    componentStalledResolved(name: string, stallInfo: ComponentStallInfo, stalledDurationMS: number): void;
+    componentUnexpectedStop(name: string, error?: Error): void;
     componentShutdownForceCompleted(name: string): void;
     componentShutdownForceTimeout(name: string, timeoutMS: number): void;
     componentStartupRollback(name: string): void;

package/dist/lib/lifecycle-manager/index.d.ts

@@ -158,7 +158,7 @@ interface RestartComponentOptions {
 /**
  * Stable, machine-readable failure codes for individual component operations
  */
-type ComponentOperationFailureCode = 'component_not_found' | 'component_already_running' | 'component_already_starting' | 'component_already_stopping' | 'component_not_running' | 'component_stalled' | 'missing_dependency' | 'dependency_not_running' | 'has_running_dependents' | 'startup_in_progress' | 'shutdown_in_progress' | 'component_startup_timeout' | 'component_shutdown_timeout' | 'restart_stop_failed' | 'restart_start_failed' | 'unknown_error';
+type ComponentOperationFailureCode = 'component_not_found' | 'component_already_running' | 'component_already_starting' | 'component_already_stopping' | 'component_not_running' | 'component_stalled' | 'missing_dependency' | 'dependency_not_running' | 'has_running_dependents' | 'startup_in_progress' | 'shutdown_in_progress' | 'component_unexpected_stop' | 'component_startup_timeout' | 'component_shutdown_timeout' | 'restart_stop_failed' | 'restart_start_failed' | 'unknown_error';
 /**
  * Failure codes for unregister operations
  */
@@ -202,7 +202,7 @@ interface StartupResult {
     /** Reason for failure (when success is false) */
     reason?: string;
     /** Error code (when success is false) */
-    code?: 'already_in_progress' | 'shutdown_in_progress' | 'dependency_cycle' | 'no_components_registered' | 'stalled_components_exist' | 'partial_state' | 'required_component_failed' | 'startup_timeout' | 'unknown_error';
+    code?: 'already_in_progress' | 'component_unexpected_stop' | 'shutdown_in_progress' | 'dependency_cycle' | 'no_components_registered' | 'stalled_components_exist' | 'partial_state' | 'required_component_failed' | 'startup_timeout' | 'unknown_error';
     /** Error object (when success is false due to dependency cycle or unknown error) */
     error?: Error;
     /** Total startup duration in milliseconds */
@@ -956,6 +956,10 @@ declare abstract class BaseComponent {
     protected name: string;
     /** Reference to component-scoped lifecycle (set by manager when registered) */
     protected lifecycle: ComponentLifecycleRef;
+    /** @internal Set by LifecycleManager while the component is running. */
+    private _unexpectedStopHandler?;
+    /** @internal Incremented whenever the unexpected-stop handler is re-armed or cleared. */
+    private _unexpectedStopGeneration;
     /**
      * Create a new component
      *
@@ -964,6 +968,10 @@ declare abstract class BaseComponent {
      * @throws {InvalidComponentNameError} If name doesn't match kebab-case pattern
      */
     constructor(rootLogger: Logger, options: ComponentOptions);
+    /** @internal Called by LifecycleManager after a successful start. */
+    _setUnexpectedStopHandler(handler: (error?: Error) => boolean): void;
+    /** @internal Called by LifecycleManager when stop begins or component is unregistered. */
+    _clearUnexpectedStopHandler(): void;
     /**
      * Start the component
      *
@@ -1146,6 +1154,28 @@ declare abstract class BaseComponent {
      * Check if component is optional
      */
     isOptional(): boolean;
+    /**
+     * Run-scoped unexpected-stop callback. Rebound by LifecycleManager on each
+     * successful start so captured references from older runs go stale.
+     */
+    protected reportUnexpectedStop: (error?: Error) => boolean;
+    /**
+     * Get this component's own status from the manager's perspective.
+     *
+     * Equivalent to `this.lifecycle.getComponentStatus(this.getName())` but without
+     * needing to pass the name. Returns `undefined` if the component is not registered.
+     *
+     * Check `status?.state === 'running'` to test whether the component is currently running.
+     */
+    protected getSelfStatus(): ComponentStatus | undefined;
+    /**
+     * Capture a run-scoped unexpected-stop reporter for async listeners created during start().
+     *
+     * Unlike calling `this.reportUnexpectedStop()` later, the returned callback becomes a no-op
+     * once the component is stopped, unregistered, or restarted. This prevents stale listeners
+     * from a previous run from stopping a newer run of the same component instance.
+     */
+    protected getUnexpectedStopReporter(): (error?: Error) => boolean;
 }
 
 /**
@@ -1179,7 +1209,11 @@ declare class LifecycleManager extends EventEmitterProtected implements Lifecycl
     private componentTimestamps;
     private componentErrors;
     private componentStartAttemptTokens;
+    private componentStopAttemptTokens;
+    private pendingForceStopWaiters;
+    private unexpectedStopsDuringStartup;
     private isStarting;
+    private autoAttachedSignalsDuringStartup;
     private isStarted;
     private isShuttingDown;
     private shutdownToken;
@@ -1592,6 +1626,45 @@ declare class LifecycleManager extends EventEmitterProtected implements Lifecycl
     private autoAttachSignals;
     private autoDetachSignalsIfIdle;
     private monitorLateStartupCompletion;
+    private consumeUnexpectedStopsDuringStartup;
+    /**
+     * Issues and returns a unique stop attempt token for a component.
+     *
+     * Each stop attempt (graceful or force-retry) gets a unique token.
+     * The late-resolution handler captures this token in its closure so it can
+     * skip any stall entries that were created by a *later* stop attempt — e.g. a
+     * force-retry that also timed out after the original graceful promise floated
+     * in the background.
+     */
+    private issueStopAttemptToken;
+    private createPendingForceStopWaiter;
+    private resolvePendingForceStopWaiters;
+    /**
+     * Called when a stop promise eventually resolves after its timeout path already fired.
+     *
+     * Usually this means a previously stalled component's original stop() or
+     * onShutdownForce() promise finally resolved, so the manager can clear the
+     * stall and transition the component to stopped without a manual retry.
+     *
+     * There is one extra overlap case for graceful stop(): stop() can resolve
+     * after the graceful timeout but before onShutdownForce() itself times out.
+     * In that window no stall entry exists yet, but the component still finished
+     * stopping cleanly, so we finalize it here and let the later force-timeout
+     * path observe the already-stopped state and no-op. This overlap fix is
+     * scoped to the same stop token and will not cross a later retry attempt.
+     *
+     * Two guards prevent stale floating promises from incorrectly clearing state:
+     *
+     * 1. token guard — if a newer stop attempt (e.g. a retryStalled
+     *    force-retry) has started since this promise was launched, its token
+     *    won't match and we bail out immediately.
+     *
+     * 2. state/stall guard — if the component was unregistered, restarted, or
+     *    already cleared by another path, there will be neither a matching stall
+     *    entry nor the force-phase overlap state, so we bail out.
+     */
+    private handleLateStopResolution;
+    private handleComponentUnexpectedStop;
     /**
      * Safe emit wrapper - prevents event handler errors from breaking lifecycle
      */
@@ -1713,36 +1786,27 @@ declare class LifecycleManager extends EventEmitterProtected implements Lifecycl
      */
     private armRepeatedShutdownAfterFailure;
     /**
-     * Handle reload request - calls custom callback or broadcasts to components.
+     * Shared dispatch path for reload/info/debug requests. Logs the dispatch,
+     * emits the signal event, then either invokes the user-supplied callback
+     * (passing the broadcast function so the user controls when/whether to
+     * broadcast) or broadcasts directly when no callback is configured.
      *
      * When called from signal handlers (source='signal'), the Promise is started
-     * but not awaited due to Node.js signal handler constraints. Components are
-     * still notified and the work completes, but return values are not accessible.
-     *
+     * but not awaited — Node.js signal handlers cannot return values, so results
+     * are not accessible. Components are still notified and the work completes.
      * When called from manual triggers (source='trigger'), the Promise is awaited
      * and results are returned for programmatic use.
-     *
-     * @param source - Whether triggered from signal manager or manual trigger
      */
+    private handleSignalRequest;
     private handleReloadRequest;
-    /**
-     * Handle info request - calls custom callback or broadcasts to components.
-     *
-     * When called from signal handlers, the Promise executes but return values
-     * are not accessible due to Node.js signal handler constraints.
-     *
-     * @param source - Whether triggered from signal manager or manual trigger
-     */
     private handleInfoRequest;
+    private handleDebugRequest;
     /**
-     * Handle debug request - calls custom callback or broadcasts to components.
-     *
-     * When called from signal handlers, the Promise executes but return values
-     * are not accessible due to Node.js signal handler constraints.
-     *
-     * @param source - Whether triggered from signal manager or manual trigger
+     * Shared signal broadcast pipeline used by reload/info/debug.
+     * Iterates running components, runs the picked handler with timeout, and
+     * aggregates per-component results into a SignalBroadcastResult.
      */
-    private handleDebugRequest;
+    private runSignalBroadcast;
     /**
      * Broadcast reload signal to all running components.
      * Calls onReload() on components that implement it.
@@ -1962,6 +2026,15 @@ interface LifecycleManagerEventMap {
         reason?: string;
         code?: string;
     };
+    'component:stalled-resolved': {
+        name: string;
+        stallInfo: ComponentStallInfo;
+        stalledDurationMS: number;
+    };
+    'component:unexpected-stop': {
+        name: string;
+        error?: Error;
+    };
     'component:shutdown-force-completed': {
         name: string;
     };
@@ -2140,6 +2213,8 @@ declare class LifecycleManagerEvents {
         reason?: string;
         code?: string;
     }): void;
+    componentStalledResolved(name: string, stallInfo: ComponentStallInfo, stalledDurationMS: number): void;
+    componentUnexpectedStop(name: string, error?: Error): void;
     componentShutdownForceCompleted(name: string): void;
     componentShutdownForceTimeout(name: string, timeoutMS: number): void;
     componentStartupRollback(name: string): void;