lifecycleion 0.0.1

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

@@ -0,0 +1,2044 @@
+import { EventEmitterProtected } from '../event-emitter.js';
+import { Logger, LoggerService } from '../logger/index.js';
+import { ProcessSignalManagerStatus, ShutdownSignal } from '../process-signal-manager.js';
+
+/**
+ * Component configuration options passed to BaseComponent constructor
+ */
+interface ComponentOptions {
+    /** Unique component name (must be kebab-case) */
+    name: string;
+    /** Names of components this one depends on (default: []) */
+    dependencies?: string[];
+    /** If true, startup failure doesn't trigger rollback (default: false) */
+    optional?: boolean;
+    /** Time to wait for start() in milliseconds (default: 30000, 0 = disabled) */
+    startupTimeoutMS?: number;
+    /** Time to wait for graceful shutdown in milliseconds (default: 5000, minimum: 1000) */
+    shutdownGracefulTimeoutMS?: number;
+    /** Time to wait for force shutdown in milliseconds (default: 2000, minimum: 500) */
+    shutdownForceTimeoutMS?: number;
+    /** Time to wait for healthCheck() in milliseconds (default: 5000) */
+    healthCheckTimeoutMS?: number;
+    /** Time to wait for onReload/onInfo/onDebug in milliseconds (default: 5000, 0 = disabled) */
+    signalTimeoutMS?: number;
+}
+/**
+ * Possible states a component can be in
+ */
+type ComponentState = 'registered' | 'starting' | 'starting-timed-out' | 'running' | 'failed' | 'stopping' | 'force-stopping' | 'stopped' | 'stalled';
+/**
+ * Detailed status information for a component
+ */
+interface ComponentStatus {
+    /** Component name */
+    name: string;
+    /** Current state */
+    state: ComponentState;
+    /** Unix timestamp (ms) when start() completed */
+    startedAt: number | null;
+    /** Unix timestamp (ms) when stop() completed */
+    stoppedAt: number | null;
+    /** Last error from start/stop/message */
+    lastError: Error | null;
+    /** If stalled, details about why */
+    stallInfo: ComponentStallInfo | null;
+}
+/**
+ * Information about why a component is stalled
+ */
+interface ComponentStallInfo {
+    /** Component name */
+    name: string;
+    /** Which shutdown phase failed */
+    phase: 'graceful' | 'force';
+    /** Reason for stall */
+    reason: 'timeout' | 'error' | 'both';
+    /** When shutdown started for this component */
+    startedAt: number;
+    /** When the stall occurred */
+    stalledAt: number;
+    /** Error that caused the stall (if applicable) */
+    error?: Error;
+}
+/**
+ * How shutdown was triggered
+ */
+type ShutdownMethod = 'manual' | 'SIGINT' | 'SIGTERM' | 'SIGTRAP';
+/**
+ * Base interface for all operation results
+ *
+ * Provides consistent structure across all operations with common fields
+ * for success status, error handling, and optional component status.
+ */
+interface BaseOperationResult {
+    /** Whether the operation succeeded */
+    success: boolean;
+    /** Human-readable explanation if !success */
+    reason?: string;
+    /** Machine-readable failure code if !success */
+    code?: string;
+    /** Underlying error if applicable */
+    error?: Error;
+    /** Component status after the operation (if applicable) */
+    status?: ComponentStatus;
+}
+/**
+ * Result of an individual component operation (start/stop/restart)
+ */
+interface ComponentOperationResult extends BaseOperationResult {
+    /** Component name */
+    componentName: string;
+    /** Machine-readable failure code if !success */
+    code?: ComponentOperationFailureCode;
+}
+/**
+ * Options for manually starting a component
+ */
+interface StartComponentOptions {
+    /**
+     * If true, allow starting even when required dependencies are registered
+     * but not running. Missing dependencies still cause failure.
+     * This is an explicit override that bypasses normal dependency checks.
+     */
+    allowNonRunningDependencies?: boolean;
+    /**
+     * If true, allow starting a component during bulk startup (startAllComponents).
+     * By default, startComponent() is blocked during bulk operations to prevent
+     * interference with dependency ordering. However, if the component's dependencies
+     * are already running, this option allows you to start it dynamically.
+     *
+     * Note: Starting during shutdown is NEVER allowed, regardless of this option.
+     *
+     * Default: false
+     */
+    allowDuringBulkStartup?: boolean;
+    /**
+     * If true, force starting this component even if it's stalled without requiring
+     * it to be unregistered or retried via stopAllComponents({ retryStalled: true }) first.
+     *
+     * Default: false
+     */
+    forceStalled?: boolean;
+}
+/**
+ * Options for manually stopping a component
+ */
+interface StopComponentOptions {
+    /**
+     * If true, force immediate shutdown without graceful period
+     * Calls onShutdownForce() directly, bypassing normal stop() flow
+     * (default: false)
+     */
+    forceImmediate?: boolean;
+    /**
+     * Override the component's configured shutdown timeout in milliseconds
+     * If not specified, uses the component's shutdownGracefulTimeoutMS
+     * Only applies when forceImmediate is false
+     */
+    timeout?: number;
+    /**
+     * If true, allows stopping a component even if other running components depend on it
+     * Without this flag, stopping a component with running dependents will fail
+     * (default: false)
+     */
+    allowStopWithRunningDependents?: boolean;
+}
+/**
+ * Options for restarting a component (stop + start)
+ *
+ * Combines options for both stop and start phases.
+ */
+interface RestartComponentOptions {
+    /** Options for the stop phase */
+    stopOptions?: StopComponentOptions;
+    /** Options for the start phase */
+    startOptions?: StartComponentOptions;
+}
+/**
+ * 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';
+/**
+ * Failure codes for unregister operations
+ */
+type UnregisterFailureCode = 'component_not_found' | 'component_running' | 'stop_failed' | 'bulk_operation_in_progress';
+/**
+ * Additional details for why unregister stop failed
+ */
+type UnregisterStopFailureReason = 'stalled' | 'timeout' | 'error';
+/**
+ * Result of unregistering a component
+ */
+interface UnregisterComponentResult extends BaseOperationResult {
+    /** Component name */
+    componentName: string;
+    /** Machine-readable failure code if !success */
+    code?: UnregisterFailureCode;
+    /** More detail when stop_failed occurs */
+    stopFailureReason?: UnregisterStopFailureReason;
+    /** Whether the component was stopped before unregistering */
+    wasStopped: boolean;
+    /** Whether the component was found in registry */
+    wasRegistered: boolean;
+}
+/**
+ * Result of starting all components
+ */
+interface StartupResult {
+    /** True if all required components started */
+    success: boolean;
+    /** Names of components that started successfully */
+    startedComponents: string[];
+    /** Optional components that failed (app continues) */
+    failedOptionalComponents: Array<{
+        name: string;
+        error: Error;
+    }>;
+    /** Components skipped because their optional dependency failed */
+    skippedDueToDependency: string[];
+    /** Present if stalled components blocked startup */
+    blockedByStalledComponents?: string[];
+    /** 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';
+    /** Error object (when success is false due to dependency cycle or unknown error) */
+    error?: Error;
+    /** Total startup duration in milliseconds */
+    durationMS?: number;
+    /** Present if startup timed out */
+    timedOut?: boolean;
+}
+/**
+ * Result of stopping all components
+ */
+interface ShutdownResult {
+    /** True if all components stopped cleanly */
+    success: boolean;
+    /** Names of components that stopped successfully */
+    stoppedComponents: string[];
+    /** Components that failed to stop */
+    stalledComponents: ComponentStallInfo[];
+    /** How long shutdown took */
+    durationMS: number;
+    /** True if shutdown exceeded the timeout and returned partial results */
+    timedOut?: boolean;
+    /** Reason for failure (when success is false) */
+    reason?: string;
+    /** Error code (when success is false) */
+    code?: 'already_in_progress' | 'shutdown_timeout';
+}
+/**
+ * Options for stopping all components
+ */
+interface StopAllOptions {
+    /** Global timeout for entire shutdown process in milliseconds (default: 30000, 0 = disabled) */
+    timeoutMS?: number;
+    /** Retry stalled components during stopAllComponents (default: true) */
+    retryStalled?: boolean;
+    /** Stop processing further components after a stall (default: true) */
+    haltOnStall?: boolean;
+}
+/**
+ * Result of restarting all components (stop + start)
+ */
+interface RestartResult {
+    /** Shutdown phase result */
+    shutdownResult: ShutdownResult;
+    /** Startup phase result */
+    startupResult: StartupResult;
+    /** True only if both shutdown and startup succeeded */
+    success: boolean;
+}
+/**
+ * Result of sending a message to a component
+ */
+interface MessageResult {
+    /** Was message delivered to handler */
+    sent: boolean;
+    /** Does component exist */
+    componentFound: boolean;
+    /** Is component currently running */
+    componentRunning: boolean;
+    /** Does component have onMessage() method */
+    handlerImplemented: boolean;
+    /** Data returned from onMessage handler (undefined if handler returned nothing) */
+    data: unknown;
+    /** Error if handler threw */
+    error: Error | null;
+    /** True if handler timed out before responding */
+    timedOut: boolean;
+    /** Machine-readable outcome code */
+    code: 'sent' | 'not_found' | 'stopped' | 'stalled' | 'no_handler' | 'timeout' | 'error';
+}
+/**
+ * Options for sending a message to a component
+ */
+interface SendMessageOptions {
+    /**
+     * Timeout in milliseconds for awaiting a response
+     * (default: manager messageTimeoutMS, 0 = disabled)
+     */
+    timeout?: number;
+    /**
+     * Include stopped (not running, not stalled) components (default: false)
+     */
+    includeStopped?: boolean;
+    /**
+     * Include stalled components (default: false)
+     */
+    includeStalled?: boolean;
+}
+/**
+ * Options for requesting a value from a component
+ */
+interface GetValueOptions {
+    /**
+     * Include stopped (not running, not stalled) components (default: false)
+     */
+    includeStopped?: boolean;
+    /**
+     * Include stalled components (default: false)
+     */
+    includeStalled?: boolean;
+}
+/**
+ * Options for broadcasting messages to components
+ */
+interface BroadcastOptions extends SendMessageOptions {
+    /** Filter to specific component names (default: all components) */
+    componentNames?: string[];
+}
+/**
+ * Result of broadcasting a message to multiple components
+ */
+interface BroadcastResult {
+    /** Component name */
+    name: string;
+    /** Was message delivered */
+    sent: boolean;
+    /** Was component running */
+    running: boolean;
+    /** Data returned from onMessage handler (undefined if not sent or no return) */
+    data: unknown;
+    /** Error if handler threw */
+    error: Error | null;
+    /** True if handler timed out before responding */
+    timedOut: boolean;
+    /** Machine-readable outcome code */
+    code: 'sent' | 'stopped' | 'stalled' | 'no_handler' | 'timeout' | 'error';
+}
+/**
+ * Component health check result (simple or rich)
+ */
+interface ComponentHealthResult {
+    /** Is the component healthy */
+    healthy: boolean;
+    /** Human-readable status message */
+    message?: string;
+    /** Arbitrary metrics/metadata */
+    details?: Record<string, unknown>;
+}
+/**
+ * Result of checking a single component's health
+ */
+interface HealthCheckResult {
+    /** Component name */
+    name: string;
+    /** Is the component healthy */
+    healthy: boolean;
+    /** Status message from component */
+    message?: string;
+    /** Details from component */
+    details?: Record<string, unknown>;
+    /** When the check was performed */
+    checkedAt: number;
+    /** How long the check took */
+    durationMS: number;
+    /** Error if health check threw */
+    error: Error | null;
+    /** True if health check timed out */
+    timedOut: boolean;
+    /** Machine-readable outcome code */
+    code: 'ok' | 'not_found' | 'stopped' | 'stalled' | 'no_handler' | 'timeout' | 'error';
+}
+/**
+ * Aggregate health report for all components
+ */
+interface HealthReport {
+    /** True only if ALL components are healthy */
+    healthy: boolean;
+    /** Health check results for each component */
+    components: HealthCheckResult[];
+    /** When the check was performed */
+    checkedAt: number;
+    /** How long the check took */
+    durationMS: number;
+    /** True if any component timed out */
+    timedOut: boolean;
+    /** Machine-readable outcome code */
+    code: 'ok' | 'degraded' | 'timeout' | 'error';
+}
+/**
+ * Result of broadcasting a signal (reload/info/debug)
+ */
+interface SignalBroadcastResult {
+    /** Which signal was broadcast */
+    signal: 'reload' | 'info' | 'debug';
+    /** Results for each component */
+    results: ComponentSignalResult[];
+    /** True if any component timed out */
+    timedOut: boolean;
+    /** Machine-readable outcome code */
+    code: 'ok' | 'partial_timeout' | 'timeout' | 'partial_error' | 'error';
+}
+/**
+ * Result of a signal handler on a specific component
+ */
+interface ComponentSignalResult {
+    /** Component name */
+    name: string;
+    /** True if handler was called (component implements it) */
+    called: boolean;
+    /** Error if handler threw */
+    error: Error | null;
+    /** True if handler timed out before completing */
+    timedOut: boolean;
+    /** Machine-readable outcome code */
+    code: 'called' | 'no_handler' | 'timeout' | 'error';
+}
+/**
+ * Simple result type for component getValue() methods
+ * Components return this, and LifecycleManager wraps it with additional metadata
+ */
+interface ComponentValueResult<T = unknown> {
+    /** True if component has a value for the requested key */
+    found: boolean;
+    /** The value (undefined when not found) */
+    value: T | undefined;
+}
+/**
+ * Result of requesting a value from a component
+ */
+interface ValueResult<T = unknown> {
+    /** True if getValue returned non-undefined */
+    found: boolean;
+    /** The returned value */
+    value: T | undefined;
+    /** Component exists in registry */
+    componentFound: boolean;
+    /** Component is in 'running' state */
+    componentRunning: boolean;
+    /** Component has getValue() method */
+    handlerImplemented: boolean;
+    /** Who requested (for logging) */
+    requestedBy: string | null;
+    /** Machine-readable outcome code */
+    code: 'found' | 'not_found' | 'stopped' | 'stalled' | 'no_handler' | 'error';
+}
+type EventEmitterSurface = Pick<EventEmitterProtected, 'on' | 'once' | 'hasListener' | 'hasListeners' | 'listenerCount'>;
+/**
+ * Common lifecycle interface shared by LifecycleManager and ComponentLifecycle
+ *
+ * Keep in sync with public LifecycleManager API and ComponentLifecycle proxy.
+ * Purpose: define the shared surface both expose to avoid drift across the two.
+ */
+interface LifecycleCommon extends EventEmitterSurface {
+    hasComponent(name: string): boolean;
+    isComponentRunning(name: string): boolean;
+    getComponentNames(): string[];
+    getRunningComponentNames(): string[];
+    getComponentCount(): number;
+    getRunningComponentCount(): number;
+    getStalledComponentCount(): number;
+    getStoppedComponentCount(): number;
+    getComponentStatus(name: string): ComponentStatus | undefined;
+    getAllComponentStatuses(): ComponentStatus[];
+    getSystemState(): SystemState;
+    getStatus(): LifecycleManagerStatus;
+    getStalledComponents(): ComponentStallInfo[];
+    getStalledComponentNames(): string[];
+    getStoppedComponentNames(): string[];
+    getStartupOrder(): StartupOrderResult;
+    validateDependencies(): DependencyValidationResult;
+    startAllComponents(options?: StartupOptions): Promise<StartupResult>;
+    stopAllComponents(options?: StopAllOptions): Promise<ShutdownResult>;
+    restartAllComponents(options?: RestartAllOptions): Promise<RestartResult>;
+    startComponent(name: string, options?: StartComponentOptions): Promise<ComponentOperationResult>;
+    stopComponent(name: string, options?: StopComponentOptions): Promise<ComponentOperationResult>;
+    restartComponent(name: string, options?: RestartComponentOptions): Promise<ComponentOperationResult>;
+    attachSignals(): void;
+    detachSignals(): void;
+    getSignalStatus(): LifecycleSignalStatus;
+    triggerReload(): Promise<SignalBroadcastResult>;
+    triggerInfo(): Promise<SignalBroadcastResult>;
+    triggerDebug(): Promise<SignalBroadcastResult>;
+    sendMessageToComponent(componentName: string, payload: unknown, options?: SendMessageOptions): Promise<MessageResult>;
+    broadcastMessage(payload: unknown, options?: BroadcastOptions): Promise<BroadcastResult[]>;
+    checkComponentHealth(name: string): Promise<HealthCheckResult>;
+    checkAllHealth(): Promise<HealthReport>;
+    getValue<T = unknown>(componentName: string, key: string, options?: GetValueOptions): ValueResult<T>;
+}
+/**
+ * Component-scoped lifecycle interface injected into BaseComponent
+ * This is a restricted view of LifecycleManager suitable for components.
+ */
+type ComponentLifecycleRef = LifecycleCommon;
+/**
+ * Overall system state
+ */
+type SystemState = 'no-components' | 'ready' | 'starting' | 'running' | 'stalled' | 'shutting-down';
+/**
+ * Aggregated status snapshot for the lifecycle manager.
+ */
+interface LifecycleManagerStatus {
+    /** Overall system state derived from manager flags and component state */
+    systemState: SystemState;
+    /** True if any component is running (or stalled) */
+    isStarted: boolean;
+    /** True while startAllComponents() is running */
+    isStarting: boolean;
+    /** True while stopAllComponents() is running */
+    isShuttingDown: boolean;
+    /** Counts of registered, running, stopped, and stalled components */
+    counts: {
+        total: number;
+        running: number;
+        stopped: number;
+        stalled: number;
+        startTimedOut: number;
+    };
+    /** Component name lists for quick inspection */
+    components: {
+        registered: string[];
+        running: string[];
+        stopped: string[];
+        stalled: string[];
+        startTimedOut: string[];
+    };
+}
+/**
+ * Options for registering a component
+ */
+interface RegisterOptions {
+    /** Auto-start if manager is running/starting (default: false) */
+    autoStart?: boolean;
+}
+/**
+ * Options for unregistering a component
+ */
+interface UnregisterOptions {
+    /**
+     * Stop the component first if it's running (default: true)
+     * Set to false to require manual stop before unregister
+     */
+    stopIfRunning?: boolean;
+    /**
+     * If true (along with stopIfRunning), allows stopping a component even if
+     * other components depend on it before unregistering
+     * (default: false)
+     */
+    forceStop?: boolean;
+}
+/**
+ * Options for starting all components
+ */
+interface StartupOptions {
+    /** Allow start even if stalled components exist (default: false) */
+    ignoreStalledComponents?: boolean;
+    /** Global timeout for entire startup process in milliseconds (default: constructor's startupTimeoutMS) */
+    timeoutMS?: number;
+}
+/**
+ * Options for restarting all components (stop + start)
+ */
+interface RestartAllOptions {
+    /** Startup options for the start phase */
+    startupOptions?: StartupOptions;
+    /** Timeout for the shutdown phase in milliseconds (default: shutdownOptions.timeoutMS) */
+    shutdownTimeoutMS?: number;
+}
+/**
+ * Insert position for registering a component relative to the current registry list
+ */
+type InsertPosition = 'start' | 'end' | 'before' | 'after';
+/**
+ * Stable, machine-readable failure codes for registration operations
+ */
+type RegistrationFailureCode = 'duplicate_name' | 'duplicate_instance' | 'shutdown_in_progress' | 'startup_in_progress' | 'target_not_found' | 'invalid_position' | 'dependency_cycle' | 'unknown_error';
+/**
+ * Common result shape for component registration operations
+ */
+interface RegistrationResultBase extends BaseOperationResult {
+    /** Whether the component was added to the registry */
+    registered: boolean;
+    /** Component name */
+    componentName: string;
+    /** Machine-readable failure code if !success */
+    code?: RegistrationFailureCode;
+    /** Registration index before the operation (null if not previously registered) */
+    registrationIndexBefore: number | null;
+    /** Registration index after the operation (null if not registered) */
+    registrationIndexAfter: number | null;
+    /** Resolved startup order after applying dependency constraints */
+    startupOrder: string[];
+    /** Whether registration occurred during startup */
+    duringStartup?: boolean;
+    /** Whether auto-start was attempted after registration */
+    autoStartAttempted?: boolean;
+    /** Whether auto-start succeeded (only present when autoStartAttempted is true) */
+    autoStartSucceeded?: boolean;
+    /** Result of auto-start operation (only present when autoStartAttempted is true) */
+    startResult?: ComponentOperationResult;
+}
+/**
+ * Stable, machine-readable failure codes for getStartupOrder()
+ */
+type StartupOrderFailureCode = 'dependency_cycle' | 'unknown_error';
+/**
+ * Result of getStartupOrder()
+ */
+interface StartupOrderResult extends BaseOperationResult {
+    /** Resolved startup order after applying dependency constraints */
+    startupOrder: string[];
+    /** Machine-readable failure code if !success */
+    code?: StartupOrderFailureCode;
+}
+/**
+ * Result of registerComponent()
+ */
+interface RegisterComponentResult extends RegistrationResultBase {
+    action: 'register';
+}
+/**
+ * Result of insertComponentAt()
+ */
+interface InsertComponentAtResult extends RegistrationResultBase {
+    action: 'insert';
+    /** Requested insertion position */
+    requestedPosition: {
+        /**
+         * The requested position.
+         *
+         * Note: This is `string` (not just `InsertPosition`) so untyped/JS callers can
+         * still get back the original invalid value when the operation fails with
+         * `code: 'invalid_position'`.
+         */
+        position: InsertPosition | (string & {});
+        targetComponentName?: string;
+    };
+    /** Actual position where component was inserted (after dependency resolution) */
+    actualPosition?: {
+        /** The actual registry index where the component was inserted */
+        index: number;
+        /** Human-readable description of position (e.g., "at start", "after database, before api") */
+        description?: string;
+    };
+    /** True if requested relative positioning was achievable under dependency constraints */
+    manualPositionRespected: boolean;
+    /** Present when inserting before/after a target */
+    targetFound?: boolean;
+}
+/**
+ * Result of validateDependencies()
+ *
+ * Provides a report of dependency issues without throwing.
+ * Reports all issues regardless of whether components are optional - the optional
+ * flag affects startup behavior, not whether dependencies must exist.
+ */
+interface DependencyValidationResult {
+    /** True if all dependencies are valid (no circular cycles, no missing dependencies) */
+    valid: boolean;
+    /** Missing dependencies: components that depend on non-registered components */
+    missingDependencies: Array<{
+        componentName: string;
+        /** Whether the component with the missing dependency is optional */
+        componentIsOptional: boolean;
+        missingDependency: string;
+    }>;
+    /**
+     * Detected circular dependency cycles.
+     * Each cycle is an array of component names forming a circle (e.g., ['A', 'B', 'C'] means A→B→C→A).
+     */
+    circularCycles: string[][];
+    /** Summary counts for quick overview */
+    summary: {
+        /** Total number of missing dependencies */
+        totalMissingDependencies: number;
+        /** Missing dependencies from required components */
+        requiredMissingDependencies: number;
+        /** Missing dependencies from optional components */
+        optionalMissingDependencies: number;
+        /** Total number of circular dependency cycles detected */
+        totalCircularCycles: number;
+    };
+}
+/**
+ * Extended signal status with lifecycle-specific information
+ */
+interface LifecycleSignalStatus extends ProcessSignalManagerStatus {
+    /** How shutdown was triggered (null if not shut down) */
+    shutdownMethod: ShutdownMethod | null;
+}
+/**
+ * Configuration options for LifecycleManager
+ */
+interface LifecycleManagerOptions {
+    /** Name for logger scope (default: 'lifecycle-manager') */
+    name?: string;
+    /** Root logger instance (required) */
+    logger: Logger;
+    /** Global timeout for startup in ms (default: 60000, 0 = disabled) */
+    startupTimeoutMS?: number;
+    /** Default stopAllComponents options used by signal and logger hooks */
+    shutdownOptions?: StopAllOptions;
+    /** Global warning phase timeout in ms (default: 500, 0 = fire-and-forget, <0 = skip) */
+    shutdownWarningTimeoutMS?: number;
+    /** Default message timeout in ms (default: 5000, 0 = disabled) */
+    messageTimeoutMS?: number;
+    /** Auto-attach signals when first component starts (default: false) */
+    attachSignalsOnStart?: boolean;
+    /** Auto-detach signals when last component stops (default: false) */
+    detachSignalsOnStop?: boolean;
+    /** Enable Logger exit hook integration (default: false). When enabled, logger.exit() triggers graceful component shutdown before process exit. */
+    enableLoggerExitHook?: boolean;
+    /** Custom reload signal handler (called instead of default broadcast, receives broadcast function you can optionally call) */
+    onReloadRequested?: (broadcastReload: () => Promise<SignalBroadcastResult>) => void | Promise<void>;
+    /** Custom info signal handler (called instead of default broadcast, receives broadcast function you can optionally call) */
+    onInfoRequested?: (broadcastInfo: () => Promise<SignalBroadcastResult>) => void | Promise<void>;
+    /** Custom debug signal handler (called instead of default broadcast, receives broadcast function you can optionally call) */
+    onDebugRequested?: (broadcastDebug: () => Promise<SignalBroadcastResult>) => void | Promise<void>;
+}
+
+/**
+ * Abstract base class for all lifecycle-managed components
+ *
+ * Components extend this class and implement the required start() and stop() methods.
+ * They can optionally implement lifecycle hooks for shutdown phases, signal handling,
+ * health checks, messaging, and value sharing.
+ *
+ * The component's lifecycle is managed by a LifecycleManager instance which:
+ * - Calls start() during startup (with dependency ordering)
+ * - Calls stop() and optional shutdown hooks during shutdown
+ * - Provides messaging and value sharing between components
+ * - Handles signals (SIGINT, SIGTERM, SIGHUP, etc.)
+ *
+ * @example
+ * ```typescript
+ * class DatabaseComponent extends BaseComponent {
+ *   private pool?: Pool;
+ *
+ *   constructor(logger: Logger) {
+ *     super(logger, {
+ *       name: 'database',
+ *       dependencies: [],
+ *       startupTimeoutMS: 10000,
+ *       shutdownGracefulTimeoutMS: 5000,
+ *     });
+ *   }
+ *
+ *   async start() {
+ *     this.logger.info('Connecting to database...');
+ *     this.pool = await createPool(config);
+ *     this.logger.success('Connected to database');
+ *   }
+ *
+ *   async stop() {
+ *     this.logger.info('Closing database connections...');
+ *     await this.pool?.end();
+ *     this.logger.success('Database connections closed');
+ *   }
+ *
+ *   // Optional: handle graceful shutdown warning
+ *   async onShutdownWarning() {
+ *     this.logger.info('Shutdown warning - stopping new connections');
+ *     this.pool?.stopAcceptingConnections();
+ *   }
+ *
+ *   // Optional: handle reload signal
+ *   async onReload() {
+ *     this.logger.info('Reloading database configuration');
+ *     await this.reloadConfig();
+ *   }
+ *
+ *   // Optional: health check
+ *   async healthCheck() {
+ *     const isHealthy = await this.pool?.ping();
+ *     return { healthy: isHealthy, message: 'Database connection active' };
+ *   }
+ * }
+ * ```
+ */
+declare abstract class BaseComponent {
+    /** Names of components this one depends on */
+    readonly dependencies: string[];
+    /** If true, startup failure doesn't trigger rollback */
+    readonly optional: boolean;
+    /** Time to wait for start() in milliseconds */
+    readonly startupTimeoutMS: number;
+    /** Time to wait for graceful shutdown in milliseconds */
+    readonly shutdownGracefulTimeoutMS: number;
+    /** Time to wait for force shutdown in milliseconds */
+    readonly shutdownForceTimeoutMS: number;
+    /** Time to wait for healthCheck() in milliseconds */
+    readonly healthCheckTimeoutMS: number;
+    /** Time to wait for onReload/onInfo/onDebug in milliseconds */
+    readonly signalTimeoutMS: number;
+    /** Component logger (scoped to component name) */
+    protected logger: LoggerService;
+    /** Component name (kebab-case) */
+    protected name: string;
+    /** Reference to component-scoped lifecycle (set by manager when registered) */
+    protected lifecycle: ComponentLifecycleRef;
+    /**
+     * Create a new component
+     *
+     * @param rootLogger - Root logger instance (component will create scoped logger)
+     * @param options - Component configuration
+     * @throws {InvalidComponentNameError} If name doesn't match kebab-case pattern
+     */
+    constructor(rootLogger: Logger, options: ComponentOptions);
+    /**
+     * Start the component
+     *
+     * Called by the LifecycleManager when starting components.
+     * Should perform all initialization, connection setup, etc.
+     * Dependencies are guaranteed to have started before this is called.
+     *
+     * Can be sync or async - manager will await if Promise is returned.
+     *
+     * @throws Should throw an error if startup fails
+     */
+    abstract start(): Promise<void> | void;
+    /**
+     * Stop the component (graceful shutdown)
+     *
+     * Called by the LifecycleManager when stopping components.
+     * Should perform graceful cleanup, close connections, save state, etc.
+     * Dependents are guaranteed to have stopped before this is called.
+     *
+     * Can be sync or async - manager will await if Promise is returned.
+     *
+     * @throws Should throw an error if stop fails (will trigger force phase)
+     */
+    abstract stop(): Promise<void> | void;
+    /**
+     * Called when start() times out
+     *
+     * Invoked when start() exceeds startupTimeoutMS before rollback begins.
+     * Use this to set flags, abort pending work, or cleanup resources.
+     * Must be synchronous and fast - manager won't wait for it to complete.
+     */
+    onStartupAborted?(): void;
+    /**
+     * Called when stop() times out
+     *
+     * Invoked when stop() exceeds shutdownGracefulTimeoutMS before force shutdown begins.
+     * Use this to set flags or prepare for more aggressive cleanup in onShutdownForce().
+     * Must be synchronous and fast - manager won't wait for it to complete.
+     */
+    onGracefulStopTimeout?(): void;
+    /**
+     * Called before graceful shutdown to warn component
+     *
+     * Optional lifecycle hook called before stopAllComponents() begins stopping components.
+     * Use this to prepare for shutdown (stop accepting new work, drain queues, etc.)
+     *
+     * Can be sync or async - manager will await if Promise is returned.
+     */
+    onShutdownWarning?(): Promise<void> | void;
+    /**
+     * Called for force shutdown if graceful shutdown times out or throws
+     *
+     * Optional lifecycle hook called after stop() fails.
+     * Use this for more aggressive cleanup (kill connections, abandon work, etc.)
+     *
+     * Can be sync or async - manager will await if Promise is returned.
+     */
+    onShutdownForce?(): Promise<void> | void;
+    /**
+     * Called when onShutdownForce() times out
+     *
+     * Invoked when onShutdownForce() exceeds shutdownForceTimeoutMS before component is marked stalled.
+     * Must be synchronous and fast - manager won't wait for it to complete.
+     */
+    onShutdownForceAborted?(): void;
+    /**
+     * Called when reload signal (SIGHUP, R key) is received
+     *
+     * Optional signal handler for runtime reload.
+     * Use this to reload configuration, reconnect, etc. without full restart.
+     *
+     * Can be sync or async - manager will await if Promise is returned.
+     * Errors are caught and logged but don't stop the broadcast.
+     */
+    onReload?(): Promise<void> | void;
+    /**
+     * Called when info signal (SIGUSR1, I key) is received
+     *
+     * Optional signal handler for info requests.
+     * Use this to log status, metrics, or other runtime information.
+     *
+     * Can be sync or async - manager will await if Promise is returned.
+     * Errors are caught and logged but don't stop the broadcast.
+     */
+    onInfo?(): Promise<void> | void;
+    /**
+     * Called when debug signal (SIGUSR2, D key) is received
+     *
+     * Optional signal handler for debug requests.
+     * Use this to toggle debug mode, dump state, etc.
+     *
+     * Can be sync or async - manager will await if Promise is returned.
+     * Errors are caught and logged but don't stop the broadcast.
+     */
+    onDebug?(): Promise<void> | void;
+    /**
+     * Optional health check for runtime monitoring
+     *
+     * Return a simple boolean or a rich result with metadata.
+     * Called by the manager when checking component health.
+     * Only called on 'running' components.
+     *
+     * @returns boolean (healthy/unhealthy) or rich result with details
+     *
+     * @example
+     * ```typescript
+     * // Simple boolean
+     * healthCheck() {
+     *   return this.isConnected;
+     * }
+     *
+     * // Rich result with metadata
+     * async healthCheck() {
+     *   const stats = await this.getStats();
+     *   return {
+     *     healthy: stats.errorRate < 0.05,
+     *     message: stats.errorRate < 0.05 ? 'Healthy' : 'High error rate',
+     *     details: { errorRate: stats.errorRate, requestsPerSec: stats.rps }
+     *   };
+     * }
+     * ```
+     */
+    healthCheck?(): Promise<boolean | ComponentHealthResult> | boolean | ComponentHealthResult;
+    /**
+     * Optional message handler for arbitrary component messaging
+     *
+     * Receives messages from other components or external code.
+     * Can return data which will be included in MessageResult.data.
+     *
+     * @param payload - The message content (any type)
+     * @param from - Sender component name (null if external)
+     * @returns Optional data to include in response
+     *
+     * @example
+     * ```typescript
+     * async onMessage(payload: unknown, from: string | null) {
+     *   const msg = payload as { action: string; data?: unknown };
+     *
+     *   if (msg.action === 'reset') {
+     *     await this.reset();
+     *     return { success: true };
+     *   }
+     *
+     *   if (msg.action === 'getStats') {
+     *     return { connections: this.pool.size, uptime: this.uptime };
+     *   }
+     * }
+     * ```
+     */
+    onMessage?<TData = unknown>(payload: unknown, from: string | null): TData | Promise<TData>;
+    /**
+     * Optional value provider - return values on-demand for other components
+     *
+     * Called when other components or external code request a value by key.
+     * Return a structured result indicating if the value was found.
+     *
+     * @param key - The value key being requested
+     * @param from - Component name if another component requested, null if external
+     * @returns Structured result with found status and value
+     *
+     * @example
+     * ```typescript
+     * getValue(key: string, from: string | null): ComponentValueResult {
+     *   if (key === 'pool') return { found: true, value: this.pool };
+     *   else if (key === 'config') return { found: true, value: this.config };
+     *   return { found: false, value: undefined }; // Key not found
+     * }
+     * ```
+     */
+    getValue?<T = unknown>(key: string, from: string | null): ComponentValueResult<T>;
+    /**
+     * Get component name
+     */
+    getName(): string;
+    /**
+     * Get component dependencies
+     */
+    getDependencies(): string[];
+    /**
+     * Check if component is optional
+     */
+    isOptional(): boolean;
+}
+
+/**
+ * LifecycleManager - Comprehensive lifecycle orchestration system
+ *
+ * Manages startup, shutdown, and runtime control of application components.
+ * Features:
+ * - Multi-phase shutdown (global warning -> per-component graceful -> force)
+ * - Dependency-ordered component startup
+ * - Process signal integration
+ * - Component messaging and value sharing
+ * - Health checks and monitoring
+ * - Event-driven architecture
+ */
+declare class LifecycleManager extends EventEmitterProtected implements LifecycleCommon {
+    private readonly name;
+    private readonly logger;
+    private readonly rootLogger;
+    private readonly shutdownWarningTimeoutMS;
+    private readonly messageTimeoutMS;
+    private readonly startupTimeoutMS;
+    private readonly shutdownOptions?;
+    private readonly attachSignalsOnStart;
+    private readonly detachSignalsOnStop;
+    private components;
+    private runningComponents;
+    private componentStates;
+    private stalledComponents;
+    private componentTimestamps;
+    private componentErrors;
+    private isStarting;
+    private isStarted;
+    private isShuttingDown;
+    private shutdownMethod;
+    private lastShutdownResult;
+    private processSignalManager;
+    private readonly onReloadRequested?;
+    private readonly onInfoRequested?;
+    private readonly onDebugRequested?;
+    private readonly lifecycleEvents;
+    constructor(options: LifecycleManagerOptions & {
+        logger: Logger;
+    });
+    /**
+     * Register a component at the end of the registry list.
+     */
+    registerComponent(component: BaseComponent, options?: RegisterOptions): Promise<RegisterComponentResult>;
+    /**
+     * Insert a component at a specific position within the registry list.
+     *
+     * Notes:
+     * - The registry list is a manual ordering preference only.
+     * - Dependencies may override this preference; the result object includes `startupOrder`
+     *   and `manualPositionRespected` so callers can see if the request was achievable.
+     */
+    insertComponentAt(component: BaseComponent, position: InsertPosition, targetComponentName?: string, options?: RegisterOptions): Promise<InsertComponentAtResult>;
+    /**
+     * Unregister a component
+     *
+     * @param name - Component name to unregister
+     * @param options - Unregister options (stopIfRunning defaults to true)
+     *
+     * Notes:
+     * - Stopped or stalled components can be unregistered directly
+     * - Running components are stopped first by default (stopIfRunning: true)
+     * - Set stopIfRunning: false to require manual stop before unregister
+     * - If stopIfRunning is true and stop fails, unregister is aborted
+     * - If stopIfRunning is true and the component is stalled, unregister is aborted
+     * @returns True if component was unregistered, false otherwise
+     */
+    unregisterComponent(name: string, options?: UnregisterOptions): Promise<UnregisterComponentResult>;
+    /**
+     * Check if a component is registered
+     */
+    hasComponent(name: string): boolean;
+    /**
+     * Check if a component is currently running
+     */
+    isComponentRunning(name: string): boolean;
+    /**
+     * Get all registered component names
+     */
+    getComponentNames(): string[];
+    /**
+     * Get all running component names
+     */
+    getRunningComponentNames(): string[];
+    /**
+     * Get the actual component instance by name.
+     *
+     * Note: This returns the live instance registered with the manager. Mutating it
+     * directly can bypass lifecycle invariants, so treat it as read-only unless you
+     * fully control the component and understand the implications.
+     */
+    getComponentInstance(name: string): BaseComponent | undefined;
+    /**
+     * Get total component count
+     */
+    getComponentCount(): number;
+    /**
+     * Get running component count
+     */
+    getRunningComponentCount(): number;
+    /**
+     * Get stalled component count
+     */
+    getStalledComponentCount(): number;
+    /**
+     * Get stopped (not running, not stalled) component count
+     */
+    getStoppedComponentCount(): number;
+    /**
+     * Get components whose last start attempt timed out
+     */
+    getStartTimedOutComponentCount(): number;
+    /**
+     * Get detailed status for a specific component
+     */
+    getComponentStatus(name: string): ComponentStatus | undefined;
+    /**
+     * Get statuses for all components
+     */
+    getAllComponentStatuses(): ComponentStatus[];
+    /**
+     * Get overall system state
+     */
+    getSystemState(): SystemState;
+    /**
+     * Get aggregated status snapshot for the manager.
+     */
+    getStatus(): LifecycleManagerStatus;
+    /**
+     * Get information about components that are stalled (failed to stop)
+     */
+    getStalledComponents(): ComponentStallInfo[];
+    /**
+     * Get stalled component names
+     */
+    getStalledComponentNames(): string[];
+    /**
+     * Get components whose last start attempt timed out
+     */
+    getStartTimedOutComponentNames(): string[];
+    /**
+     * Get stopped (not running, not stalled) component names
+     */
+    getStoppedComponentNames(): string[];
+    /**
+     * Get resolved startup order after applying dependency constraints.
+     */
+    getStartupOrder(): StartupOrderResult;
+    /**
+     * Validate all component dependencies without throwing.
+     *
+     * Returns a report of dependency issues:
+     * - Missing dependencies (components that depend on non-registered components)
+     * - Circular dependency cycles (e.g., A→B→C→A)
+     *
+     * Reports all issues regardless of whether components are optional.
+     * The optional flag affects startup behavior (whether failures trigger rollback),
+     * not whether dependencies must exist in the registry.
+     *
+     * This is useful for pre-flight checks before starting components.
+     */
+    validateDependencies(): DependencyValidationResult;
+    /**
+     * Get the result of the last shutdown operation.
+     * Useful for debugging stalled components or tracking shutdown metrics.
+     * Returns null if no shutdown has occurred yet or after a successful restart.
+     *
+     * @returns The last shutdown result or null
+     */
+    getLastShutdownResult(): ShutdownResult | null;
+    /**
+     * Start all registered components in dependency order.
+     *
+     * Components start in topological order (dependencies before dependents).
+     * Shutdown occurs in reverse topological order.
+     *
+     * Behavior:
+     * - Rejects if some components are already running (partial state)
+     * - Sets isStarting flag during operation
+     * - On failure: triggers rollback (stops all started components)
+     * - Optional components don't trigger rollback on failure
+     * - Dependents still attempt to start if an optional dependency fails
+     * - Handles shutdown signal during startup (aborts and rolls back)
+     */
+    startAllComponents(options?: StartupOptions): Promise<StartupResult>;
+    /**
+     * Stop all running components in reverse dependency order
+     *
+     * Components stop in reverse topological order (dependents before dependencies).
+     *
+     * @param options - Optional shutdown options
+     */
+    stopAllComponents(options?: StopAllOptions): Promise<ShutdownResult>;
+    /**
+     * Restart all components (stop then start)
+     */
+    restartAllComponents(options?: RestartAllOptions): Promise<RestartResult>;
+    /**
+     * Start a specific component
+     */
+    startComponent(name: string, options?: StartComponentOptions): Promise<ComponentOperationResult>;
+    /**
+     * Stop a specific component
+     */
+    stopComponent(name: string, options?: StopComponentOptions): Promise<ComponentOperationResult>;
+    /**
+     * Restart a component (stop then start)
+     */
+    restartComponent(name: string, options?: RestartComponentOptions): Promise<ComponentOperationResult>;
+    /**
+     * Attach signal handlers for graceful shutdown, reload, info, and debug.
+     * Creates ProcessSignalManager instance if needed and attaches it.
+     * Idempotent - calling multiple times has no effect.
+     */
+    attachSignals(): void;
+    /**
+     * Detach signal handlers.
+     * Idempotent - calling multiple times has no effect.
+     */
+    detachSignals(): void;
+    /**
+     * Get status information about signal handling.
+     */
+    getSignalStatus(): LifecycleSignalStatus;
+    /**
+     * Enable Logger exit hook integration
+     *
+     * Sets up the logger's beforeExit callback to trigger graceful component shutdown.
+     * When `logger.exit(code)` is called (or `logger.error('msg', { exitCode: 1 })`),
+     * the LifecycleManager will stop all components before the process exits.
+     *
+     * The shutdown is subject to the configured shutdown timeout (default: 30000ms).
+     * If shutdown exceeds this timeout, the process will exit anyway to prevent hanging.
+     *
+     * This method is idempotent and can be called multiple times safely.
+     *
+     * **Note:** This overwrites any existing beforeExit callback on the logger.
+     * If you need custom exit logic, set it up manually with `logger.setBeforeExitCallback()`.
+     *
+     * @example
+     * ```typescript
+     * const logger = new Logger();
+     * const lifecycle = new LifecycleManager({
+     *   logger,
+     *   enableLoggerExitHook: true, // Auto-enable
+     *   shutdownOptions: { timeoutMS: 30000 },   // Max 30s for shutdown
+     * });
+     *
+     * // Or enable manually later
+     * lifecycle.enableLoggerExitHook();
+     *
+     * // Now logger.exit() will trigger graceful shutdown
+     * logger.error('Fatal error', { exitCode: 1 });
+     * // Components stop gracefully (up to shutdown timeout) before process exits
+     * ```
+     */
+    enableLoggerExitHook(): void;
+    /**
+     * Manually trigger a reload event.
+     * @returns Result of broadcasting reload to components
+     */
+    triggerReload(): Promise<SignalBroadcastResult>;
+    /**
+     * Manually trigger an info event.
+     * @returns Result of broadcasting info to components
+     */
+    triggerInfo(): Promise<SignalBroadcastResult>;
+    /**
+     * Manually trigger a debug event.
+     * @returns Result of broadcasting debug to components
+     */
+    triggerDebug(): Promise<SignalBroadcastResult>;
+    /**
+     * Send a message to a specific component
+     *
+     * Delivers a message to the component's onMessage handler if implemented.
+     * The 'from' parameter is automatically tracked based on calling context.
+     *
+     * @param componentName - Name of target component
+     * @param payload - Message payload (any type)
+     * @param options - Optional message options (timeout override)
+     * @returns Result with sent status, data returned from handler, and any errors
+     */
+    sendMessageToComponent(componentName: string, payload: unknown, options?: SendMessageOptions): Promise<MessageResult>;
+    /**
+     * Broadcast a message to multiple components
+     *
+     * Sends the same message to multiple components (by default, all running components).
+     * The 'from' parameter is automatically tracked based on calling context.
+     *
+     * @param payload - Message payload (any type)
+     * @param options - Filtering options and message timeout override
+     * @returns Array of results, one per component
+     */
+    broadcastMessage(payload: unknown, options?: BroadcastOptions): Promise<BroadcastResult[]>;
+    /**
+     * Check the health of a specific component
+     *
+     * Calls the component's healthCheck() method if implemented.
+     * Times out after component's healthCheckTimeoutMS.
+     *
+     * @param name - Component name
+     * @returns Health check result with status, message, details, and timing
+     */
+    checkComponentHealth(name: string): Promise<HealthCheckResult>;
+    /**
+     * Check the health of all running components
+     *
+     * Runs health checks on all running components in parallel.
+     * Overall health is true only if ALL components are healthy.
+     *
+     * @returns Aggregate health report with individual component results
+     */
+    checkAllHealth(): Promise<HealthReport>;
+    /**
+     * Request a value from a component by key
+     *
+     * Calls the component's getValue(key, from) method if implemented.
+     * The 'from' parameter is automatically tracked based on calling context.
+     *
+     * @param componentName - Name of component to request value from
+     * @param key - Value key to request
+     * @returns Result with found status, value, and metadata
+     */
+    getValue<T = unknown>(componentName: string, key: string, options?: GetValueOptions): ValueResult<T>;
+    /**
+     * Internal message sending with explicit 'from' parameter
+     *
+     * @param componentName - Target component name
+     * @param payload - Message payload
+     * @param from - Sender component name (null if external)
+     */
+    private sendMessageInternal;
+    /**
+     * Internal broadcast with explicit 'from' parameter
+     *
+     * @param payload - Message payload
+     * @param from - Sender component name (null if external)
+     * @param options - Filtering options
+     */
+    private broadcastMessageInternal;
+    /**
+     * Internal getValue with explicit 'from' parameter
+     *
+     * @param componentName - Target component name
+     * @param key - Value key
+     * @param from - Requester component name (null if external)
+     */
+    private getValueInternal;
+    private updateStartedFlag;
+    /**
+     * Internal method that handles component registration logic.
+     * Used by both registerComponent and insertComponentAt.
+     */
+    private registerComponentInternal;
+    private stopAllComponentsInternal;
+    /**
+     * Retry shutdown for a stalled component.
+     * Attempts the force phase directly to avoid re-running a failing stop().
+     */
+    private retryStalledComponent;
+    /**
+     * Internal start component method - bypasses bulk operation checks
+     * Used by both startComponent() and startAllComponents()
+     */
+    private startComponentInternal;
+    /**
+     * Internal stop component method - bypasses bulk operation checks
+     * Implements individual component graceful -> force shutdown (global warning handled elsewhere)
+     */
+    private stopComponentInternal;
+    /**
+     * Two-phase shutdown: graceful -> force (global warning handled by stopAllComponents)
+     *
+     * Phase 1: Graceful (always - calls stop())
+     * Phase 2: Force (if Phase 1 failed - calls onShutdownForce())
+     */
+    private shutdownComponent;
+    /**
+     * Global warning phase (stopAllComponents only)
+     * Calls onShutdownWarning() on running components with a global timeout
+     */
+    private runShutdownWarningPhase;
+    /**
+     * Phase 2: Graceful shutdown
+     * Calls stop() with timeout
+     */
+    private shutdownComponentGraceful;
+    /**
+     * Phase 3: Force shutdown
+     * Calls onShutdownForce() with timeout, or marks as stalled if not implemented
+     */
+    private shutdownComponentForce;
+    /**
+     * Get a component by name
+     */
+    private getComponent;
+    /**
+     * Get all components that depend on the specified component (reverse lookup)
+     * @param name - Component name to find dependents for
+     * @returns Array of component names that depend on this component
+     */
+    private getDependents;
+    /**
+     * Get running components that depend on the specified component
+     * @param name - Component name to check
+     * @returns Array of running component names that depend on this component
+     */
+    private getRunningDependents;
+    /**
+     * Check if a component is a required dependency during startup
+     * Used to prevent registering dependencies mid-startup which would break ordering
+     * @param componentName - Component name to check
+     * @returns true if this component would be a required dependency
+     */
+    private isRequiredDependencyDuringStartup;
+    /**
+     * Check if a component instance is already registered
+     */
+    private hasComponentInstance;
+    /**
+     * Rollback startup by stopping all started components in reverse order
+     * Used when a required component fails to start during startAllComponents()
+     */
+    private rollbackStartup;
+    /**
+     * Safe emit wrapper - prevents event handler errors from breaking lifecycle
+     */
+    private safeEmit;
+    private buildRegisterResultFailure;
+    private buildInsertResultFailure;
+    private getComponentIndex;
+    private isInsertPosition;
+    private getInsertIndex;
+    private isManualPositionRespected;
+    /**
+     * Dependency-aware startup order.
+     *
+     * - Only registered components are included.
+     * - Missing dependencies are ignored for ordering (they are validated at start time).
+     * - Cycles throw DependencyCycleError (programmer error).
+     */
+    private getStartupOrderInternal;
+    /**
+     * Find a single dependency cycle (for error reporting during registration)
+     * Returns the first cycle found, or empty array if no cycle exists
+     *
+     * Performance note: This method exits early after finding the first cycle,
+     * which is optimal for hot paths (registration, startup order resolution).
+     * For comprehensive validation that needs ALL cycles, use findAllCircularCycles().
+     */
+    private findDependencyCycle;
+    /**
+     * Find circular dependency cycles using Depth-First Search (DFS) with cycle detection.
+     *
+     * Algorithm: DFS with visited set and recursion stack tracking
+     * - Uses 'visited' set to ensure each node is processed exactly once (prevents infinite loops)
+     * - Uses 'inStack' set to track the current DFS recursion path
+     * - When a node in the current path is encountered again, a cycle is detected
+     * - Extracts the cycle from the path and continues searching for more cycles
+     *
+     * Time Complexity: O(V + E) where V = components, E = dependency edges
+     * Space Complexity: O(V) for visited/inStack sets and recursion stack
+     *
+     * Performance note: This method finds a representative set of cycles while ensuring
+     * each node is visited once (prevents infinite loops). For hot paths that only need
+     * one cycle, use findDependencyCycle() which exits early.
+     *
+     * Returns an array of detected cycles, where each cycle is an array of component names.
+     */
+    private findAllCircularCycles;
+    /**
+     * Handle shutdown signal - initiates stopAllComponents().
+     * Double signal protection: if already shutting down, log warning and ignore.
+     */
+    private handleShutdownRequest;
+    /**
+     * Handle reload request - calls custom callback or broadcasts to components.
+     *
+     * 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.
+     *
+     * 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 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;
+    /**
+     * 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
+     */
+    private handleDebugRequest;
+    /**
+     * Broadcast reload signal to all running components.
+     * Calls onReload() on components that implement it.
+     * Continues on errors - collects all results.
+     */
+    private broadcastReload;
+    /**
+     * Broadcast info signal to all running components.
+     * Calls onInfo() on components that implement it.
+     * Continues on errors - collects all results.
+     */
+    private broadcastInfo;
+    /**
+     * Broadcast debug signal to all running components.
+     * Calls onDebug() on components that implement it.
+     * Continues on errors - collects all results.
+     */
+    private broadcastDebug;
+}
+
+interface LifecycleManagerEventMap {
+    'component:unregistered': {
+        name: string;
+        duringShutdown?: boolean;
+    };
+    'component:start-skipped': {
+        name: string;
+        reason: string;
+    };
+    'component:start-failed-optional': {
+        name: string;
+        error?: Error;
+    };
+    'lifecycle-manager:started': {
+        startedComponents: string[];
+        failedOptionalComponents: StartupResult['failedOptionalComponents'];
+        skippedComponents: string[];
+    };
+    'lifecycle-manager:signals-attached': undefined;
+    'lifecycle-manager:signals-detached': undefined;
+    'component:health-check-started': {
+        name: string;
+    };
+    'component:health-check-completed': {
+        name: string;
+        healthy: boolean;
+        message?: string;
+        details?: ComponentHealthResult['details'];
+        durationMS: number;
+        timedOut: boolean;
+    };
+    'component:health-check-failed': {
+        name: string;
+        error: Error;
+    };
+    'component:message-sent': {
+        componentName: string;
+        from: string | null;
+        payload: unknown;
+    };
+    'component:message-failed': {
+        componentName: string;
+        from: string | null;
+        error: Error;
+        timedOut: boolean;
+        code: MessageResult['code'];
+        componentFound?: boolean;
+        componentRunning?: boolean;
+        handlerImplemented?: boolean;
+        data?: unknown;
+    };
+    'component:broadcast-started': {
+        from: string | null;
+        payload: unknown;
+    };
+    'component:broadcast-completed': {
+        from: string | null;
+        resultsCount: number;
+        results: BroadcastResult[];
+    };
+    'component:value-requested': {
+        componentName: string;
+        key: string;
+        from: string | null;
+    };
+    'component:value-returned': {
+        componentName: string;
+        key: string;
+        from: string | null;
+        found: boolean;
+        value: unknown;
+        componentFound: boolean;
+        componentRunning: boolean;
+        handlerImplemented: boolean;
+        requestedBy: string | null;
+        code: ValueResult['code'];
+    };
+    'component:registration-rejected': {
+        name: string;
+        reason: RegistrationFailureCode;
+        message?: string;
+        target?: string | null;
+        cycle?: string[];
+        registrationIndexBefore?: number | null;
+        registrationIndexAfter?: number | null;
+        startupOrder?: string[];
+        requestedPosition?: InsertComponentAtResult['requestedPosition'];
+        manualPositionRespected?: boolean;
+        targetFound?: boolean;
+    };
+    'component:registered': {
+        name: string;
+        index: number | null;
+        action: RegisterComponentResult['action'] | InsertComponentAtResult['action'];
+        registrationIndexBefore: number | null;
+        registrationIndexAfter: number | null;
+        startupOrder: string[];
+        requestedPosition?: InsertComponentAtResult['requestedPosition'];
+        actualPosition?: InsertComponentAtResult['actualPosition'];
+        manualPositionRespected?: boolean;
+        targetFound?: boolean;
+        duringStartup?: boolean;
+        autoStartAttempted?: boolean;
+        autoStartSucceeded?: boolean;
+    };
+    'lifecycle-manager:shutdown-initiated': {
+        method: ShutdownMethod;
+        duringStartup: boolean;
+    };
+    'lifecycle-manager:shutdown-completed': {
+        durationMS: number;
+        stoppedComponents: string[];
+        stalledComponents: ComponentStallInfo[];
+        method: ShutdownMethod;
+        duringStartup: boolean;
+    };
+    'component:starting': {
+        name: string;
+    };
+    'component:started': {
+        name: string;
+        status?: ComponentStatus;
+    };
+    'component:start-timeout': {
+        name: string;
+        error: Error;
+        timeoutMS?: number;
+        reason?: string;
+    };
+    'component:start-failed': {
+        name: string;
+        error: Error;
+        reason?: string;
+    };
+    'lifecycle-manager:shutdown-warning': {
+        timeoutMS: number;
+    };
+    'component:shutdown-warning': {
+        name: string;
+    };
+    'component:shutdown-warning-completed': {
+        name: string;
+    };
+    'lifecycle-manager:shutdown-warning-completed': {
+        timeoutMS: number;
+    };
+    'component:shutdown-warning-timeout': {
+        name: string;
+        timeoutMS: number;
+    };
+    'lifecycle-manager:shutdown-warning-timeout': {
+        timeoutMS: number;
+        pending: string[];
+    };
+    'component:stopping': {
+        name: string;
+    };
+    'component:stopped': {
+        name: string;
+        status?: ComponentStatus;
+    };
+    'component:stop-timeout': {
+        name: string;
+        error: Error;
+        timeoutMS?: number;
+        reason?: string;
+    };
+    'component:shutdown-force': {
+        name: string;
+        context: {
+            gracefulPhaseRan: boolean;
+            gracefulTimedOut: boolean;
+        };
+    };
+    'component:stalled': {
+        name: string;
+        stallInfo: ComponentStallInfo;
+        reason?: string;
+        code?: string;
+    };
+    'component:shutdown-force-completed': {
+        name: string;
+    };
+    'component:shutdown-force-timeout': {
+        name: string;
+        timeoutMS: number;
+    };
+    'component:startup-rollback': {
+        name: string;
+    };
+    'signal:shutdown': {
+        method: ShutdownSignal;
+    };
+    'signal:reload': undefined;
+    'signal:info': undefined;
+    'signal:debug': undefined;
+    'component:reload-started': {
+        name: string;
+    };
+    'component:reload-completed': {
+        name: string;
+    };
+    'component:reload-failed': {
+        name: string;
+        error: Error;
+    };
+    'component:info-started': {
+        name: string;
+    };
+    'component:info-completed': {
+        name: string;
+    };
+    'component:info-failed': {
+        name: string;
+        error: Error;
+    };
+    'component:debug-started': {
+        name: string;
+    };
+    'component:debug-completed': {
+        name: string;
+    };
+    'component:debug-failed': {
+        name: string;
+        error: Error;
+    };
+}
+type LifecycleManagerEventName = keyof LifecycleManagerEventMap;
+type LifecycleManagerEmit = <K extends LifecycleManagerEventName>(event: K, data: LifecycleManagerEventMap[K]) => void;
+declare class LifecycleManagerEvents {
+    private readonly emit;
+    constructor(emit: LifecycleManagerEmit);
+    componentUnregistered(name: string, wasDuringShutdown?: boolean): void;
+    componentStartSkipped(name: string, reason: string): void;
+    componentStartFailedOptional(name: string, error?: Error): void;
+    lifecycleManagerStarted(startedComponents: string[], failedOptionalComponents: StartupResult['failedOptionalComponents'], skippedComponents: string[]): void;
+    lifecycleManagerSignalsAttached(): void;
+    lifecycleManagerSignalsDetached(): void;
+    componentHealthCheckStarted(name: string): void;
+    componentHealthCheckCompleted(input: {
+        name: string;
+        healthy: boolean;
+        message?: string;
+        details?: ComponentHealthResult['details'];
+        durationMS: number;
+        timedOut: boolean;
+    }): void;
+    componentHealthCheckFailed(name: string, error: Error): void;
+    componentMessageSent(input: {
+        componentName: string;
+        from: string | null;
+        payload: unknown;
+    }): void;
+    componentMessageFailed(componentName: string, from: string | null, error: Error, info?: {
+        timedOut?: boolean;
+        code?: MessageResult['code'];
+        componentFound?: boolean;
+        componentRunning?: boolean;
+        handlerImplemented?: boolean;
+        data?: unknown;
+    }): void;
+    componentBroadcastStarted(from: string | null, payload: unknown): void;
+    componentBroadcastCompleted(from: string | null, resultsCount: number, results: BroadcastResult[]): void;
+    componentValueRequested(componentName: string, key: string, from: string | null): void;
+    componentValueReturned(componentName: string, key: string, from: string | null, input: {
+        found: boolean;
+        value: unknown;
+        componentFound: boolean;
+        componentRunning: boolean;
+        handlerImplemented: boolean;
+        requestedBy: string | null;
+        code: ValueResult['code'];
+    }): void;
+    componentRegistrationRejected(input: {
+        name: string;
+        reason: RegistrationFailureCode;
+        message?: string;
+        target?: string | null;
+        cycle?: string[];
+        registrationIndexBefore?: number | null;
+        registrationIndexAfter?: number | null;
+        startupOrder?: string[];
+        requestedPosition?: InsertComponentAtResult['requestedPosition'];
+        manualPositionRespected?: boolean;
+        targetFound?: boolean;
+    }): void;
+    componentRegistered(input: {
+        name: string;
+        index: number | null;
+        action: RegisterComponentResult['action'] | InsertComponentAtResult['action'];
+        registrationIndexBefore: number | null;
+        registrationIndexAfter: number | null;
+        startupOrder: string[];
+        requestedPosition?: InsertComponentAtResult['requestedPosition'];
+        actualPosition?: InsertComponentAtResult['actualPosition'];
+        manualPositionRespected?: boolean;
+        targetFound?: boolean;
+        duringStartup?: boolean;
+        autoStartAttempted?: boolean;
+        autoStartSucceeded?: boolean;
+    }): void;
+    lifecycleManagerShutdownInitiated(method: ShutdownMethod, isDuringStartup: boolean): void;
+    lifecycleManagerShutdownCompleted(input: {
+        durationMS: number;
+        stoppedComponents: string[];
+        stalledComponents: ComponentStallInfo[];
+        method: ShutdownMethod;
+        duringStartup: boolean;
+    }): void;
+    componentStarting(name: string): void;
+    componentStarted(name: string, status?: ComponentStatus): void;
+    componentStartTimeout(name: string, error: Error, info?: {
+        timeoutMS?: number;
+        reason?: string;
+    }): void;
+    componentStartFailed(name: string, error: Error, info?: {
+        reason?: string;
+    }): void;
+    lifecycleManagerShutdownWarning(timeoutMS: number): void;
+    componentShutdownWarning(name: string): void;
+    componentShutdownWarningCompleted(name: string): void;
+    lifecycleManagerShutdownWarningCompleted(timeoutMS: number): void;
+    componentShutdownWarningTimeout(name: string, timeoutMS: number): void;
+    lifecycleManagerShutdownWarningTimeout(timeoutMS: number, pending: string[]): void;
+    componentStopping(name: string): void;
+    componentStopped(name: string, status?: ComponentStatus): void;
+    componentStopTimeout(name: string, error: Error, info?: {
+        timeoutMS?: number;
+        reason?: string;
+    }): void;
+    componentShutdownForce(input: {
+        name: string;
+        context: {
+            gracefulPhaseRan: boolean;
+            gracefulTimedOut: boolean;
+        };
+    }): void;
+    componentStalled(name: string, stallInfo: ComponentStallInfo, info?: {
+        reason?: string;
+        code?: string;
+    }): void;
+    componentShutdownForceCompleted(name: string): void;
+    componentShutdownForceTimeout(name: string, timeoutMS: number): void;
+    componentStartupRollback(name: string): void;
+    signalShutdown(method: ShutdownSignal): void;
+    signalReload(): void;
+    signalInfo(): void;
+    signalDebug(): void;
+    componentReloadStarted(name: string): void;
+    componentReloadCompleted(name: string): void;
+    componentReloadFailed(name: string, error: Error): void;
+    componentInfoStarted(name: string): void;
+    componentInfoCompleted(name: string): void;
+    componentInfoFailed(name: string, error: Error): void;
+    componentDebugStarted(name: string): void;
+    componentDebugCompleted(name: string): void;
+    componentDebugFailed(name: string, error: Error): void;
+}
+
+/**
+ * Error thrown when a component name doesn't match kebab-case validation
+ *
+ * Component names must match the pattern: `/^[a-z][a-z0-9]*(-[a-z0-9]+)*$/`
+ *
+ * Valid names: 'database', 'web-server', 'api-gateway-v2'
+ * Invalid names: 'Database', 'web_server', 'WebServer', '', 'my server'
+ */
+declare class InvalidComponentNameError extends Error {
+    errPrefix: string;
+    errType: string;
+    errCode: string;
+    additionalInfo: {
+        name: string;
+    };
+    constructor(additionalInfo: {
+        name: string;
+    });
+}
+/**
+ * Error thrown when component registration fails
+ *
+ * Common causes:
+ * - Duplicate component name
+ * - Registration attempted during shutdown
+ * - Invalid registration options
+ */
+declare class ComponentRegistrationError extends Error {
+    errPrefix: string;
+    errType: string;
+    errCode: string;
+    additionalInfo: Record<string, unknown>;
+    constructor(message: string, additionalInfo?: Record<string, unknown>);
+}
+/**
+ * Error thrown when a circular dependency is detected
+ *
+ * Example: Component A depends on B, B depends on C, C depends on A
+ */
+declare class DependencyCycleError extends Error {
+    errPrefix: string;
+    errType: string;
+    errCode: string;
+    additionalInfo: {
+        cycle: string[];
+    };
+    constructor(additionalInfo: {
+        cycle: string[];
+    });
+}
+/**
+ * Error thrown when a component depends on another component that doesn't exist
+ */
+declare class MissingDependencyError extends Error {
+    errPrefix: string;
+    errType: string;
+    errCode: string;
+    additionalInfo: {
+        componentName: string;
+        missingDependency: string;
+    };
+    constructor(additionalInfo: {
+        componentName: string;
+        missingDependency: string;
+    });
+}
+/**
+ * Error thrown when a component fails to start
+ *
+ * This wraps the underlying error and provides context about which component failed
+ */
+declare class ComponentStartupError extends Error {
+    errPrefix: string;
+    errType: string;
+    errCode: string;
+    additionalInfo: {
+        componentName: string;
+    };
+    cause?: Error;
+    constructor(additionalInfo: {
+        componentName: string;
+    }, cause?: Error);
+}
+/**
+ * Error thrown when a component start operation times out
+ */
+declare class ComponentStartTimeoutError extends Error {
+    errPrefix: string;
+    errType: string;
+    errCode: string;
+    additionalInfo: {
+        componentName: string;
+        timeoutMS: number;
+    };
+    constructor(additionalInfo: {
+        componentName: string;
+        timeoutMS: number;
+    });
+}
+/**
+ * Error thrown when a component stop operation times out
+ */
+declare class ComponentStopTimeoutError extends Error {
+    errPrefix: string;
+    errType: string;
+    errCode: string;
+    additionalInfo: {
+        componentName: string;
+        timeoutMS: number;
+    };
+    constructor(additionalInfo: {
+        componentName: string;
+        timeoutMS: number;
+    });
+}
+/**
+ * Error thrown when the global startup timeout is exceeded
+ */
+declare class StartupTimeoutError extends Error {
+    errPrefix: string;
+    errType: string;
+    errCode: string;
+    additionalInfo: {
+        timeoutMS: number;
+        startedCount: number;
+    };
+    constructor(additionalInfo: {
+        timeoutMS: number;
+        startedCount: number;
+    });
+}
+/**
+ * Error thrown when a component is not found in the registry
+ */
+declare class ComponentNotFoundError extends Error {
+    errPrefix: string;
+    errType: string;
+    errCode: string;
+    additionalInfo: {
+        componentName: string;
+    };
+    constructor(additionalInfo: {
+        componentName: string;
+    });
+}
+/**
+ * Error prefix constant for all lifecycle manager errors
+ */
+declare const lifecycleManagerErrPrefix = "LifecycleManagerErr";
+/**
+ * Error type constants
+ */
+declare const lifecycleManagerErrTypes: {
+    readonly Component: "Component";
+    readonly Dependency: "Dependency";
+    readonly Lifecycle: "Lifecycle";
+};
+/**
+ * Error code constants
+ */
+declare const lifecycleManagerErrCodes: {
+    readonly InvalidName: "InvalidName";
+    readonly RegistrationFailed: "RegistrationFailed";
+    readonly CyclicDependency: "CyclicDependency";
+    readonly NotFound: "NotFound";
+    readonly StartupFailed: "StartupFailed";
+    readonly StartupTimeout: "StartupTimeout";
+    readonly StartTimeout: "StartTimeout";
+    readonly StopTimeout: "StopTimeout";
+};
+
+export { BaseComponent, type BaseOperationResult, type BroadcastOptions, type BroadcastResult, type ComponentHealthResult, ComponentNotFoundError, type ComponentOperationFailureCode, type ComponentOperationResult, type ComponentOptions, ComponentRegistrationError, type ComponentSignalResult, type ComponentStallInfo, ComponentStartTimeoutError, ComponentStartupError, type ComponentState, type ComponentStatus, ComponentStopTimeoutError, type ComponentValueResult, DependencyCycleError, type DependencyValidationResult, type GetValueOptions, type HealthCheckResult, type HealthReport, type InsertComponentAtResult, type InsertPosition, InvalidComponentNameError, LifecycleManager, type LifecycleManagerEmit, type LifecycleManagerEventMap, type LifecycleManagerEventName, LifecycleManagerEvents, type LifecycleManagerOptions, type LifecycleManagerStatus, type MessageResult, MissingDependencyError, type RegisterComponentResult, type RegisterOptions, type RegistrationFailureCode, type RestartComponentOptions, type RestartResult, type SendMessageOptions, type ShutdownMethod, type ShutdownResult, type SignalBroadcastResult, type StartComponentOptions, type StartupOptions, type StartupOrderFailureCode, type StartupOrderResult, type StartupResult, StartupTimeoutError, type StopAllOptions, type StopComponentOptions, type SystemState, type UnregisterComponentResult, type UnregisterFailureCode, type UnregisterOptions, type ValueResult, lifecycleManagerErrCodes, lifecycleManagerErrPrefix, lifecycleManagerErrTypes };