/**
 * Infrastructure Context Types for Declarative Infrastructure API
 *
 * This module defines the interfaces for the Infrastructure Context (Aggregate Root)
 * and Unit of Work patterns. These types are isomorphic and can be used in both
 * Lambda and browser contexts.
 *
 * @module declarative-api/infrastructure-context.types
 */
import type { Stage } from './core.types';
import type { IResourceEntity } from './resource.types';
import type { IResourceRepository } from './repository.types';
import type { IEventBusMediator } from './mediator.types';
import type { IResourceFactoryRegistry, IResourceBuilder } from './factory.types';
import type { IObserverRegistry } from './observer.types';
import type { IPermissionChain } from './permission-chain.types';
import type { ICommandExecutor } from './command.types';
import type { IDecoratorRegistry } from './decorator.types';
import type { ResourceEvent } from './event.types';
/**
 * Interface representing the RuntimeInfraStack for type definitions.
 * This is a minimal interface to avoid circular dependencies with CDK types.
 * The actual RuntimeInfraStack implements IFrameworkResourceProvider.
 *
 * @see IFrameworkResourceProvider in @infra/interfaces
 */
export interface IRuntimeInfraStackReference {
    /** Service name for resource naming */
    readonly serviceName: string;
    /** Deployment stage */
    readonly stage: Stage;
}
/**
 * Unit of Work status type.
 *
 * Tracks the current state of a unit of work transaction.
 */
export type UnitOfWorkStatus = 'active' | 'committed' | 'rolled_back' | 'failed';
/**
 * All valid unit of work status values.
 */
export declare const UNIT_OF_WORK_STATUSES: readonly UnitOfWorkStatus[];
/**
 * Type guard to check if a value is a valid UnitOfWorkStatus.
 *
 * @param value - The value to check
 * @returns True if the value is a valid UnitOfWorkStatus
 */
export declare function isValidUnitOfWorkStatus(value: unknown): value is UnitOfWorkStatus;
/**
 * Unit of Work operation type.
 *
 * Tracks the type of operation performed within a unit of work.
 */
export type UnitOfWorkOperationType = 'create' | 'modify' | 'delete';
/**
 * A single operation within a Unit of Work.
 */
export interface UnitOfWorkOperation {
    /** Unique operation identifier */
    readonly operationId: string;
    /** Type of operation */
    readonly type: UnitOfWorkOperationType;
    /** Resource ID being operated on */
    readonly resourceId: string;
    /** The resource entity (for create/modify) */
    readonly resource?: IResourceEntity;
    /** Timestamp of the operation */
    readonly timestamp: Date;
    /** Whether the operation has been executed */
    readonly executed: boolean;
}
/**
 * Result of a Unit of Work commit operation.
 */
export interface UnitOfWorkCommitResult {
    /** Whether the commit was successful */
    readonly success: boolean;
    /** Number of operations committed */
    readonly operationCount: number;
    /** Created resources */
    readonly createdResources: readonly IResourceEntity[];
    /** Error message if commit failed */
    readonly error?: string;
    /** Duration of the commit in milliseconds */
    readonly durationMs: number;
}
/**
 * Result of a Unit of Work rollback operation.
 */
export interface UnitOfWorkRollbackResult {
    /** Whether the rollback was successful */
    readonly success: boolean;
    /** Number of operations rolled back */
    readonly operationCount: number;
    /** Error message if rollback failed */
    readonly error?: string;
    /** Duration of the rollback in milliseconds */
    readonly durationMs: number;
}
/**
 * Unit of Work interface for batch operations.
 *
 * Implements the Unit of Work pattern for managing batch operations
 * with atomicity guarantees. Either all operations succeed and are
 * committed, or all operations are rolled back.
 *
 * Implements: Unit of Work Pattern
 *
 * @example
 * ```typescript
 * const uow = context.beginTransaction();
 *
 * try {
 *   uow.registerCreate(tableEntity);
 *   uow.registerCreate(queueEntity);
 *   const result = uow.commit();
 *   console.log(`Created ${result.operationCount} resources`);
 * } catch (error) {
 *   uow.rollback();
 *   throw error;
 * }
 * ```
 *
 * Validates: Requirements 1.6
 */
export interface IUnitOfWork {
    /** Unique identifier for this unit of work */
    readonly id: string;
    /** Current status of the unit of work */
    readonly status: UnitOfWorkStatus;
    /** All operations registered in this unit of work */
    readonly operations: readonly UnitOfWorkOperation[];
    /**
     * Register a resource creation operation.
     *
     * @param resource - The resource entity to create
     */
    registerCreate(resource: IResourceEntity): void;
    /**
     * Register a resource modification operation.
     *
     * @param resource - The resource entity to modify
     */
    registerModify(resource: IResourceEntity): void;
    /**
     * Register a resource deletion operation.
     *
     * @param resourceId - The ID of the resource to delete
     */
    registerDelete(resourceId: string): void;
    /**
     * Check if the unit of work has any pending operations.
     *
     * @returns True if there are pending operations
     */
    hasPendingOperations(): boolean;
    /**
     * Get the count of pending operations.
     *
     * @returns The number of pending operations
     */
    getPendingCount(): number;
    /**
     * Commit all registered operations.
     *
     * Executes all operations in dependency order. If any operation
     * fails, all previously executed operations are rolled back.
     *
     * @returns The commit result
     * @throws Error if the unit of work is not in 'active' status
     */
    commit(): UnitOfWorkCommitResult;
    /**
     * Rollback all executed operations.
     *
     * Undoes all operations that were executed during commit,
     * in reverse order.
     *
     * @returns The rollback result
     */
    rollback(): UnitOfWorkRollbackResult;
    /**
     * Clear all pending operations without executing them.
     */
    clear(): void;
}
/**
 * Options for creating an Infrastructure Context.
 *
 * IMPORTANT: infraStack is now REQUIRED. Standalone mode is no longer supported.
 * All resource creation must flow through RuntimeInfraStack for framework integration.
 *
 * Validates: Requirements 6.1
 */
export interface InfrastructureContextOptions {
    /**
     * REQUIRED: Reference to RuntimeInfraStack.
     *
     * The Declarative API no longer supports standalone mode.
     * All resources must be created through the framework abstraction layer.
     *
     * @example
     * ```typescript
     * const infraStack = new RuntimeInfraStack(app, 'Infra', {
     *   stage: 'dev',
     *   serviceName: 'my-service',
     * });
     *
     * const context = createInfrastructureContext({
     *   infraStack,
     *   serviceName: 'my-service',
     *   stage: 'dev',
     * });
     * ```
     */
    readonly infraStack: IRuntimeInfraStackReference;
    /** Unique context identifier */
    readonly contextId?: string;
    /** Service name for resource naming (defaults to infraStack's serviceName) */
    readonly serviceName?: string;
    /** Deployment stage (defaults to infraStack's stage) */
    readonly stage?: Stage;
    /** Maximum event log size */
    readonly maxEventLogSize?: number;
    /** Enable debug logging */
    readonly debug?: boolean;
}
/**
 * Result of creating a resource through the context.
 */
export interface ResourceCreationResult<T extends IResourceEntity = IResourceEntity> {
    /** Whether the creation was successful */
    readonly success: boolean;
    /** The created resource */
    readonly resource?: T;
    /** Error message if creation failed */
    readonly error?: string;
    /** Events published during creation */
    readonly events: readonly ResourceEvent[];
    /** Duration of the creation in milliseconds */
    readonly durationMs: number;
}
/**
 * Infrastructure Context interface (Aggregate Root).
 *
 * The Infrastructure Context is the single entry point for managing all
 * infrastructure resources. It encapsulates all resource entities and
 * provides consistency guarantees through the Aggregate Root pattern.
 *
 * Key responsibilities:
 * - Resource creation through builders and factories
 * - Resource access through repository
 * - Event publishing through mediator
 * - Batch operations through Unit of Work
 * - Consistency invariants between related resources
 *
 * Implements: DDD Aggregate Root, Unit of Work
 *
 * @example
 * ```typescript
 * // Create context
 * const context = new InfrastructureContext({
 *   serviceName: 'user-service',
 *   stage: 'prod',
 *   stack: cdkStack,
 *   lambdaRole: lambdaRole,
 * });
 *
 * // Create resource through builder
 * const builder = context.factories.getOrThrow('dynamodb').getBuilder('users-table');
 * const table = context.createResource(builder.withProps(tableProps).build());
 *
 * // Access through repository
 * const retrieved = context.repository.getById('users-table');
 *
 * // Batch operations
 * const uow = context.beginTransaction();
 * uow.registerCreate(table1);
 * uow.registerCreate(table2);
 * uow.commit();
 * ```
 *
 * Validates: Requirements 1.1, 1.2, 1.3, 1.4, 1.5, 1.6
 */
export interface IInfrastructureContext {
    /** Unique context identifier */
    readonly contextId: string;
    /** Service name for resource naming */
    readonly serviceName: string;
    /** Deployment stage */
    readonly stage: Stage;
    /** Resource factory registry */
    readonly factories: IResourceFactoryRegistry;
    /** Resource repository for accessing created resources */
    readonly repository: IResourceRepository;
    /** Event bus mediator for event-driven communication */
    readonly mediator: IEventBusMediator;
    /** Observer registry for resource lifecycle observers */
    readonly observers: IObserverRegistry;
    /** Permission chain for IAM permission handling */
    readonly permissionChain: IPermissionChain;
    /** Command executor for deferred resource creation */
    readonly commandExecutor: ICommandExecutor;
    /** Decorator registry for cross-cutting concerns */
    readonly decorators: IDecoratorRegistry;
    /**
     * Create a resource through a builder.
     *
     * The resource is automatically registered in the repository
     * and domain events are published through the mediator.
     *
     * @typeParam T - The resource entity type
     * @param builder - The builder to create the resource from
     * @returns The creation result
     */
    createResource<T extends IResourceEntity>(builder: IResourceBuilder<T, unknown>): ResourceCreationResult<T>;
    /**
     * Register an existing resource in the context.
     *
     * Use this to add resources that were created outside the context
     * (e.g., imported from another stack).
     *
     * @param resource - The resource to register
     */
    registerResource(resource: IResourceEntity): void;
    /**
     * Begin a new Unit of Work transaction.
     *
     * Use this for batch operations that should be atomic.
     *
     * @returns A new Unit of Work instance
     */
    beginTransaction(): IUnitOfWork;
    /**
     * Commit all pending commands.
     *
     * Executes all commands in the command executor in dependency order.
     *
     * @returns Array of created resources
     */
    commit(): IResourceEntity[];
    /**
     * Rollback all executed commands.
     *
     * Undoes all commands that were executed during commit.
     */
    rollback(): void;
    /**
     * Generate a resource name following naming conventions.
     *
     * @param baseName - The base name for the resource
     * @returns The generated resource name
     */
    resourceName(baseName: string): string;
    /**
     * Check if a resource exists in the context.
     *
     * @param resourceId - The resource ID to check
     * @returns True if the resource exists
     */
    hasResource(resourceId: string): boolean;
    /**
     * Get the count of resources in the context.
     *
     * @returns The number of resources
     */
    getResourceCount(): number;
    /**
     * Clear all resources from the context.
     *
     * Use with caution - this removes all cached resources.
     */
    clear(): void;
}
/**
 * Factory function type for creating Infrastructure Context instances.
 */
export type InfrastructureContextFactory = (options: InfrastructureContextOptions) => IInfrastructureContext;
