/**
 * Specification Pattern Types
 *
 * This module defines the interfaces and base classes for the Specification pattern,
 * enabling composable validation and query logic for infrastructure resources.
 *
 * The Specification pattern allows:
 * - Composable validation rules (and/or/not)
 * - Reusable query predicates
 * - Type-safe configuration validation
 *
 * @module declarative-api/specification.types
 */
/**
 * Validation error severity levels.
 */
export type ValidationSeverity = 'error' | 'warning';
/**
 * Validation error returned when a specification is not satisfied.
 *
 * Contains detailed information about what failed and where,
 * enabling precise error reporting and debugging.
 *
 * @example
 * ```typescript
 * const error: ValidationError = {
 *   path: 'tableName',
 *   message: 'Table name must start with a letter',
 *   code: 'INVALID_TABLE_NAME',
 *   severity: 'error',
 * };
 * ```
 *
 * Validates: Requirements 11.4
 */
export interface ValidationError {
    /** Path to the invalid property (dot notation for nested) */
    readonly path: string;
    /** Human-readable error message */
    readonly message: string;
    /** Machine-readable error code for programmatic handling */
    readonly code: string;
    /** Severity level (error = must fix, warning = should fix) */
    readonly severity: ValidationSeverity;
}
/**
 * Specification interface for composable validation and queries.
 *
 * Implements the Specification pattern with support for:
 * - Boolean satisfaction check
 * - Detailed error collection
 * - Logical composition (and/or/not)
 *
 * @typeParam T - The type of candidate being validated
 *
 * @example
 * ```typescript
 * const nameSpec: ISpecification<TableConfig> = new ValidTableNameSpec();
 * const requiredSpec: ISpecification<TableConfig> = new RequiredFieldSpec('partitionKey');
 *
 * // Compose specifications
 * const combinedSpec = nameSpec.and(requiredSpec);
 *
 * // Check satisfaction
 * if (combinedSpec.isSatisfiedBy(config)) {
 *   // Valid configuration
 * } else {
 *   const errors = combinedSpec.getErrors(config);
 *   // Handle validation errors
 * }
 * ```
 *
 * Validates: Requirements 11.1, 11.2
 */
export interface ISpecification<T> {
    /**
     * Check if the specification is satisfied by the candidate.
     *
     * @param candidate - The value to check
     * @returns True if the specification is satisfied
     */
    isSatisfiedBy(candidate: T): boolean;
    /**
     * Get validation errors for the candidate.
     *
     * Returns an empty array if the specification is satisfied.
     *
     * @param candidate - The value to validate
     * @returns Array of validation errors (empty if valid)
     */
    getErrors(candidate: T): ValidationError[];
    /**
     * Create a new specification that is satisfied when both
     * this specification AND the other specification are satisfied.
     *
     * @param other - The specification to combine with
     * @returns A new AndSpecification
     */
    and(other: ISpecification<T>): ISpecification<T>;
    /**
     * Create a new specification that is satisfied when either
     * this specification OR the other specification is satisfied.
     *
     * @param other - The specification to combine with
     * @returns A new OrSpecification
     */
    or(other: ISpecification<T>): ISpecification<T>;
    /**
     * Create a new specification that is satisfied when
     * this specification is NOT satisfied.
     *
     * @returns A new NotSpecification
     */
    not(): ISpecification<T>;
}
/**
 * Async specification interface for validation that requires async operations.
 *
 * Extends the base specification with async methods for checking
 * existing resources in AWS or other async validation.
 *
 * @typeParam T - The type of candidate being validated
 *
 * @example
 * ```typescript
 * const uniqueNameSpec: IAsyncSpecification<TableConfig> = new UniqueTableNameSpec(dynamoClient);
 *
 * // Async validation
 * if (await uniqueNameSpec.isSatisfiedByAsync(config)) {
 *   // Table name is unique
 * }
 * ```
 *
 * Validates: Requirements 11.6
 */
export interface IAsyncSpecification<T> extends ISpecification<T> {
    /**
     * Async check if the specification is satisfied by the candidate.
     *
     * Use this for validation that requires async operations like
     * checking existing AWS resources.
     *
     * @param candidate - The value to check
     * @returns Promise resolving to true if satisfied
     */
    isSatisfiedByAsync(candidate: T): Promise<boolean>;
    /**
     * Async get validation errors for the candidate.
     *
     * @param candidate - The value to validate
     * @returns Promise resolving to array of validation errors
     */
    getErrorsAsync(candidate: T): Promise<ValidationError[]>;
}
