import { PureContainer } from '@worktif/utils';
import type { TiesInstance } from '../../../lib/runtime-web/types';
/**
 * Container initialization phases in deterministic order.
 * Each phase must complete before the next phase can begin.
 */
export type ContainerPhase = 'creating' | 'loading-metadata' | 'registering-core' | 'registering-microservices' | 'validating' | 'ready' | 'failed';
/**
 * Error information for container initialization failures.
 */
export interface ContainerError {
    phase: ContainerPhase;
    serviceName?: string;
    hashKey?: string;
    error: string;
    timestamp: number;
}
/**
 * Container scope state for tracking service scopes and instances.
 */
export interface ContainerScopeState {
    defaultScope: 'singleton' | 'transient';
    serviceScopes: Map<string, 'singleton' | 'transient'>;
    singletonInstances: Map<string, any>;
    cleanupHooks: Map<string, () => Promise<void> | void>;
}
/**
 * Container initialization state tracking.
 */
export interface ContainerInitializationState {
    phase: ContainerPhase;
    startTime: number;
    currentPhaseStartTime: number;
    coreServicesRegistered: number;
    microserviceServicesRegistered: number;
    totalExpectedServices: number;
    errors: ContainerError[];
}
/**
 * Dependency metadata for hash-based service registration.
 */
export interface DependencyMetadata {
    className: string;
    hashKey: string;
    serviceType: 'singleton' | 'transient' | 'constant';
    dependencies: string[];
}
/**
 * Service scope configuration for container management.
 */
export interface ServiceScopeConfig {
    serviceName: string;
    hashKey: string;
    scope: 'singleton' | 'transient';
    cleanupHook?: () => Promise<void> | void;
}
/**
 * Container Lifecycle Manager orchestrates the deterministic initialization of DI containers.
 *
 * Ensures that container creation, service registration, and validation occur in a specific
 * order to prevent race conditions where Lambda handlers attempt to resolve dependencies
 * before the container is fully populated.
 *
 * The lifecycle follows these phases:
 * 1. creating - Create the PureContainer instance
 * 2. loading-metadata - Load dependency metadata for hash-based keys
 * 3. registering-core - Register core services from core pipeline
 * 4. registering-microservices - Register microservice-specific services
 * 5. validating - Validate all dependencies are registered
 * 6. ready - Container is ready for handler execution
 *
 * @example
 * ```typescript
 * const manager = new ContainerLifecycleManager();
 * const container = await manager.initializeContainer();
 *
 * // Container is guaranteed to be fully populated
 * const handler = manager.getHandler('payments.charge');
 * ```
 */
export declare class ContainerLifecycleManager {
    private sharedContainer;
    private initializationState;
    private scopeState;
    private readonly tiesRegistrar;
    private readonly diagnosticsManager;
    private readonly errorRecoveryManager;
    private readonly statePersistence;
    constructor();
    /**
     * Initialize container with deterministic order.
     *
     * Follows the complete lifecycle:
     * 1. Create container instance
     * 2. Load dependency metadata
     * 3. Register core services
     * 4. Register microservice services
     * 5. Validate completeness
     *
     * @param coreTiesClasses - Core service Ties classes
     * @param microserviceTiesClasses - Microservice Ties classes
     * @param metadata - Optional dependency metadata for hash-based keys
     * @returns Fully initialized and validated container
     * @throws DIContainerError if any phase fails
     */
    initializeContainer(coreTiesClasses?: TiesInstance[], microserviceTiesClasses?: TiesInstance[], metadata?: DependencyMetadata[]): Promise<PureContainer<string>>;
    /**
     * Validate that all declared dependencies are registered.
     *
     * Checks that all services expected from the Ties classes are actually
     * registered in the container. This prevents runtime dependency resolution
     * errors by catching missing services early.
     *
     * @param container - Container to validate
     * @param tiesClasses - All Ties classes that should have registered services
     * @throws Error if any required dependencies are missing
     */
    validateContainerCompleteness(container: PureContainer<string>, tiesClasses: TiesInstance[]): void;
    /**
     * Get the shared container instance.
     *
     * Returns the single shared container instance that was created during
     * initialization. All handlers must use this same instance to ensure
     * consistent dependency resolution.
     *
     * @returns The shared container instance
     * @throws DIContainerError if container is not initialized
     */
    getSharedContainer(): PureContainer<string>;
    /**
     * Get current initialization state.
     *
     * Provides access to the current phase, timing information, and any errors
     * that occurred during initialization. Useful for debugging and monitoring.
     *
     * @returns Current initialization state
     */
    getInitializationState(): ContainerInitializationState;
    /**
     * Check if container is ready for handler execution.
     *
     * @returns True if container is in 'ready' phase
     */
    isReady(): boolean;
    /**
     * Check if container initialization failed.
     *
     * @returns True if container is in 'failed' phase
     */
    hasFailed(): boolean;
    /**
     * Get initialization errors.
     *
     * @returns Array of errors that occurred during initialization
     */
    getErrors(): ContainerError[];
    /**
     * Execute a specific initialization phase.
     *
     * @param phase - Phase to execute
     * @param operation - Operation to perform in this phase
     */
    private executePhase;
    /**
     * Set the current initialization phase.
     *
     * @param phase - New phase to set
     */
    private setPhase;
    /**
     * Add an error to the initialization state.
     *
     * @param phase - Phase where error occurred
     * @param error - Error message
     * @param serviceName - Optional service name
     * @param hashKey - Optional hash key
     */
    private addError;
    /**
     * Handle initialization error by setting failed state.
     *
     * @param error - Error that occurred
     */
    private handleInitializationError;
    /**
     * Load dependency metadata for hash-based service registration.
     *
     * Currently a placeholder for future metadata loading functionality.
     * Will be used to load build-time generated metadata for stable hash keys.
     *
     * @param metadata - Dependency metadata to load
     */
    private loadDependencyMetadata;
    /**
     * Create initial initialization state.
     *
     * @returns Initial state object
     */
    private createInitialState;
    /**
     * Reset initialization state for new initialization.
     */
    private resetInitializationState;
    /**
     * Get comprehensive diagnostics for the container.
     *
     * @returns Container diagnostics with introspection information
     */
    getDiagnostics(): any;
    /**
     * Generate detailed error message with diagnostic context.
     *
     * @param error - Error to enhance
     * @param context - Additional context information
     * @returns Enhanced error message with diagnostics
     */
    generateDetailedErrorMessage(error: Error, context?: {
        phase?: string;
        serviceName?: string;
        hashKey?: string;
        lambdaId?: string;
    }): string;
    /**
     * Attempt to register services with error recovery.
     *
     * @param tiesClasses - Ties classes to register
     * @returns Registration attempt results
     */
    registerServicesWithRecovery(tiesClasses: TiesInstance[]): Promise<any[]>;
    /**
     * Get cached service instance for performance optimization.
     *
     * Uses the state persistence manager to cache service instances
     * across Lambda invocations for improved performance.
     *
     * @param serviceKey - Service key to resolve
     * @returns Cached or resolved service instance
     */
    getCachedServiceInstance(serviceKey: string): any;
    /**
     * Get cached hash computation for performance optimization.
     *
     * @param classCode - Class code to hash
     * @param hashFunction - Hash computation function
     * @returns Cached or computed hash value
     */
    getCachedHashComputation(classCode: string, hashFunction: (code: string) => string): string;
    /**
     * Register cleanup hook for graceful service shutdown.
     *
     * @param cleanup - Cleanup hook to register
     */
    registerCleanupHook(cleanup: any): void;
    /**
     * Perform graceful container cleanup.
     *
     * Should be called when the Lambda container is being shut down.
     */
    performCleanup(): Promise<void>;
    /**
     * Get container persistence state information.
     *
     * @returns Persistence state or null if not initialized
     */
    getPersistenceState(): any;
    /**
     * Get performance metrics for container operations.
     *
     * @returns Performance metrics including resolution times and cache hit ratios
     */
    getPerformanceMetrics(): any;
    /**
     * Check if container state is persisted across invocations.
     *
     * @returns True if container state is persisted
     */
    isContainerPersisted(): boolean;
    /**
     * Get container access statistics.
     *
     * @returns Access count and timing information
     */
    getAccessStatistics(): any;
    /**
     * Clear performance caches to free memory.
     *
     * Useful for memory management in long-running Lambda containers.
     */
    clearPerformanceCaches(): void;
    /**
     * Configure service scope configuration (singleton by default).
     *
     * Sets up the default singleton scope for all services and initializes
     * scope management state for proper service lifecycle handling.
     */
    private configureScopeManagement;
    /**
     * Configure scope for a specific service.
     *
     * @param serviceName - Name of the service
     * @param hashKey - Hash key for the service
     * @param scope - Scope configuration ('singleton' or 'transient')
     * @param cleanupHook - Optional cleanup hook for service disposal
     */
    configureServiceScope(serviceName: string, hashKey: string, scope: 'singleton' | 'transient', cleanupHook?: () => Promise<void> | void): void;
    /**
     * Get service scope configuration.
     *
     * @param hashKey - Hash key for the service
     * @returns Service scope ('singleton' or 'transient')
     */
    getServiceScope(hashKey: string): 'singleton' | 'transient';
    /**
     * Resolve service with proper scope handling.
     *
     * For singleton services, returns the same instance across all resolutions.
     * For transient services, creates new instances for each resolution.
     *
     * @param serviceKey - Service key to resolve
     * @returns Service instance according to scope configuration
     */
    resolveServiceWithScope(serviceKey: string): any;
    /**
     * Validate service scope configuration consistency.
     *
     * Ensures that scope configuration is consistent with service design
     * and that all configured scopes are valid.
     *
     * @throws DIContainerError if scope configuration is inconsistent
     */
    validateServiceScopes(): void;
    /**
     * Get all services with their scope configurations.
     *
     * @returns Map of service hash keys to their scope configurations
     */
    getServiceScopeConfigurations(): Map<string, 'singleton' | 'transient'>;
    /**
     * Dispose of services that implement cleanup interfaces.
     *
     * Calls cleanup hooks for services that need graceful shutdown.
     * This is called during container cleanup.
     */
    disposeServices(): Promise<void>;
    /**
     * Create initial scope state.
     *
     * @returns Initial container scope state
     */
    private createInitialScopeState;
}
