/**
 * @fileoverview Result Pattern Constants
 * @module @ark.alliance/core/result/constants/result.constants
 *
 * Centralized constants for the Result pattern.
 * Avoids hardcoded values throughout the codebase.
 *
 * @author Armand Richelet-Kleinberg ; with Anthropic Claude Opus 4.5 model
 */
/**
 * Standard error codes used throughout the Result pattern.
 */
declare const ErrorCodes: {
    readonly FAILURE: "FAILURE";
    readonly UNEXPECTED: "UNEXPECTED";
    readonly UNAUTHORIZED: "UNAUTHORIZED";
    readonly FORBIDDEN: "FORBIDDEN";
    readonly ALREADY: "ALREADY";
    readonly NOT_FOUND: "NOT_FOUND";
    readonly BAD_PREREQUISITES: "BAD_PREREQUISITES";
    readonly BAD_PARAMETERS: "BAD_PARAMETERS";
    readonly CANCELLED: "CANCELLED";
    readonly TIMEOUT: "TIMEOUT";
    readonly NO_CONNECTION: "NO_CONNECTION";
    readonly NOT_IMPLEMENTED: "NOT_IMPLEMENTED";
    readonly RATE_LIMITED: "RATE_LIMITED";
    readonly CIRCUIT_OPEN: "CIRCUIT_OPEN";
    readonly BULKHEAD_REJECTED: "BULKHEAD_REJECTED";
    readonly VALIDATION_ERROR: "VALIDATION_ERROR";
    readonly CONFLICT: "CONFLICT";
    readonly UNKNOWN: "UNKNOWN";
    readonly MAP_ERROR: "MAP_ERROR";
    readonly SERVICE_ERROR: "SERVICE_ERROR";
    readonly OPERATION_CANCELLED: "OPERATION_CANCELLED";
    readonly SERVICE_NOT_RUNNING: "SERVICE_NOT_RUNNING";
    readonly INVALID_STATE: "INVALID_STATE";
    readonly START_FAILED: "START_FAILED";
    readonly STOP_FAILED: "STOP_FAILED";
};
type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
declare const DefaultMessages: {
    readonly FAILURE: "Operation failed";
    readonly UNEXPECTED: "An unexpected error occurred";
    readonly UNAUTHORIZED: "Unauthorized access";
    readonly FORBIDDEN: "Access forbidden";
    readonly ALREADY: "Operation already completed";
    readonly NOT_FOUND: "Resource not found";
    readonly BAD_PREREQUISITES: "Prerequisites not met";
    readonly BAD_PARAMETERS: "Invalid parameters";
    readonly CANCELLED: "Operation cancelled";
    readonly TIMEOUT: "Operation timed out";
    readonly NO_CONNECTION: "No connection available";
    readonly NOT_IMPLEMENTED: "Operation not implemented";
    readonly RATE_LIMITED: "Rate limit exceeded";
    readonly CIRCUIT_OPEN: "Circuit breaker is open";
    readonly BULKHEAD_REJECTED: "Bulkhead rejected request";
    readonly VALIDATION_ERROR: "Validation failed";
    readonly CONFLICT: "Resource conflict";
    readonly UNKNOWN: "Unknown error";
};
declare const HttpStatusCodes: {
    readonly OK: 200;
    readonly CREATED: 201;
    readonly ACCEPTED: 202;
    readonly NO_CONTENT: 204;
    readonly BAD_REQUEST: 400;
    readonly UNAUTHORIZED: 401;
    readonly FORBIDDEN: 403;
    readonly NOT_FOUND: 404;
    readonly REQUEST_TIMEOUT: 408;
    readonly CONFLICT: 409;
    readonly PRECONDITION_FAILED: 412;
    readonly TOO_MANY_REQUESTS: 429;
    readonly CLIENT_CLOSED_REQUEST: 499;
    readonly INTERNAL_SERVER_ERROR: 500;
    readonly NOT_IMPLEMENTED: 501;
    readonly SERVICE_UNAVAILABLE: 503;
};
type HttpStatusCode = (typeof HttpStatusCodes)[keyof typeof HttpStatusCodes];
declare const TimingDefaults: {
    readonly DEFAULT_TIMEOUT_MS: 30000;
    readonly DEFAULT_RETRY_DELAY_MS: 100;
    readonly DEFAULT_MAX_RETRY_DELAY_MS: 30000;
    readonly DEFAULT_CIRCUIT_RESET_MS: 30000;
    readonly DEFAULT_RATE_LIMIT_WINDOW_MS: 60000;
    readonly DEFAULT_LOCK_TIMEOUT_MS: 30000;
    readonly DEFAULT_RECOVERY_DELAY_MS: 5000;
    readonly DEFAULT_CACHE_TTL_MS: 300000;
};
declare const RetryDefaults: {
    readonly MAX_ATTEMPTS: 3;
    readonly BACKOFF_MULTIPLIER: 2;
    readonly JITTER_FACTOR: 0.1;
    readonly MAX_JITTER_FACTOR: 0.5;
};
declare const CircuitBreakerDefaults: {
    readonly FAILURE_THRESHOLD: 5;
    readonly SUCCESS_THRESHOLD: 2;
    readonly HALF_OPEN_MAX_ATTEMPTS: 3;
    readonly SAMPLING_DURATION_MS: 60000;
};
declare const BulkheadDefaults: {
    readonly MAX_CONCURRENT: 10;
    readonly MAX_QUEUE_SIZE: 100;
    readonly QUEUE_TIMEOUT_MS: 30000;
};
declare const RateLimitDefaults: {
    readonly REQUESTS_PER_WINDOW: 100;
    readonly WINDOW_SIZE_MS: 60000;
    readonly BUCKET_CAPACITY: 100;
    readonly REFILL_RATE: 10;
};
declare const ServiceDefaults: {
    readonly INSTANCE_KEY: "default";
    readonly STREAMING_NAMESPACE: "/";
    readonly MAX_RECOVERY_ATTEMPTS: 3;
    readonly AUTO_RECOVER: true;
    readonly ENABLE_STREAMING: false;
};

/**
 * @fileoverview Result Status Enumeration
 * @module @ark.alliance/core/result/enums/ResultStatus
 *
 * Defines all possible transaction/operation result states.
 * Used by the Result<T> class for type-safe status handling.
 *
 * @remarks
 * Status categories:
 * - **Success**: SUCCESS
 * - **Client Errors**: VALIDATION_ERROR, BAD_PARAMETERS, BAD_PREREQUISITES, UNAUTHORIZED, NOT_FOUND, ALREADY
 * - **Server Errors**: FAILURE, UNEXPECTED, SERVICE_UNAVAILABLE
 * - **Transient**: TIMEOUT, RATE_LIMITED, NO_CONNECTION, CANCELLED
 * - **Meta**: NONE, PENDING, NOT_IMPLEMENTED
 *
 * @author Armand Richelet-Kleinberg ; with Anthropic Claude Opus 4.5 model
 */
/**
 * Enumeration of all possible result statuses for operations.
 *
 * @enum {string}
 */
declare enum ResultStatus {
    /** No status set (initial/default state). */
    NONE = "NONE",
    /** Operation completed successfully. */
    SUCCESS = "SUCCESS",
    /** Operation failed with a known error. */
    FAILURE = "FAILURE",
    /** Unexpected exception occurred. */
    UNEXPECTED = "UNEXPECTED",
    /** Operation is still in progress. */
    PENDING = "PENDING",
    /** Operation timed out. */
    TIMEOUT = "TIMEOUT",
    /** Authorization/authentication failed. */
    UNAUTHORIZED = "UNAUTHORIZED",
    /** Operation already completed (idempotency check). */
    ALREADY = "ALREADY",
    /** Validation errors occurred. */
    VALIDATION_ERROR = "VALIDATION_ERROR",
    /** Resource not found. */
    NOT_FOUND = "NOT_FOUND",
    /** Pre-conditions/prerequisites not met. */
    BAD_PREREQUISITES = "BAD_PREREQUISITES",
    /** Invalid parameters provided. */
    BAD_PARAMETERS = "BAD_PARAMETERS",
    /** Operation cancelled by user or system. */
    CANCELLED = "CANCELLED",
    /** Rate limit exceeded. */
    RATE_LIMITED = "RATE_LIMITED",
    /** Service unavailable. */
    SERVICE_UNAVAILABLE = "SERVICE_UNAVAILABLE",
    /** No network connection available. */
    NO_CONNECTION = "NO_CONNECTION",
    /** Operation not implemented. */
    NOT_IMPLEMENTED = "NOT_IMPLEMENTED",
    /** Forbidden - authenticated but not authorized */
    FORBIDDEN = "FORBIDDEN",
    /** Conflict - resource state conflict */
    CONFLICT = "CONFLICT",
    /** Circuit breaker is open */
    CIRCUIT_OPEN = "CIRCUIT_OPEN",
    /** Bulkhead rejected - too many concurrent requests */
    BULKHEAD_REJECTED = "BULKHEAD_REJECTED"
}
/**
 * Type alias for result status string values.
 */
type ResultStatusType = `${ResultStatus}`;
/**
 * Checks if status indicates success.
 *
 * @param status - Status to check.
 * @returns True if operation was successful.
 */
declare function isSuccessStatus(status: ResultStatus): boolean;
/**
 * Checks if status indicates not success (any non-success state).
 *
 * @param status - Status to check.
 * @returns True if operation was not successful.
 */
declare function isNotSuccessStatus(status: ResultStatus): boolean;
/**
 * Checks if status indicates an unexpected/unhandled error.
 */
declare function isUnexpectedStatus(status: ResultStatus): boolean;
/**
 * Checks if status indicates a validation or parameter error.
 */
declare function isValidationErrorStatus(status: ResultStatus): boolean;
/**
 * Checks if status indicates a network/connection error.
 */
declare function isNetworkErrorStatus(status: ResultStatus): boolean;
/**
 * Checks if status indicates a retryable transient error.
 */
declare function isRetryableStatus(status: ResultStatus): boolean;
/**
 * Checks if status indicates a terminal error (cannot be retried).
 */
declare function isTerminalStatus(status: ResultStatus): boolean;
declare function isUnauthorizedStatus(status: ResultStatus): boolean;
declare function isForbiddenStatus(status: ResultStatus): boolean;
declare function isNotFoundStatus(status: ResultStatus): boolean;
declare function isAlreadyStatus(status: ResultStatus): boolean;
declare function isCancelledStatus(status: ResultStatus): boolean;
declare function isTimeoutStatus(status: ResultStatus): boolean;
declare function isPendingStatus(status: ResultStatus): boolean;
declare function isNotImplementedStatus(status: ResultStatus): boolean;
declare function isRateLimitedStatus(status: ResultStatus): boolean;
declare function isCircuitOpenStatus(status: ResultStatus): boolean;
declare function isBulkheadRejectedStatus(status: ResultStatus): boolean;
/**
 * Maps a ResultStatus to the appropriate HTTP status code.
 *
 * @param status - The ResultStatus to map.
 * @returns The corresponding HTTP status code.
 */
declare function toHttpStatusCode(status: ResultStatus): number;

/**
 * @fileoverview Error Detail Interface
 * @module @ark.alliance/core/result/interfaces/IErrorDetail
 *
 * Structured error information for Result pattern.
 * Provides comprehensive error context for debugging and API responses.
 *
 * @author Armand Richelet-Kleinberg ; with Anthropic Claude Opus 4.5 model
 */
/**
 * AI-generated suggestions for error handling.
 *
 * @interface IAISuggestions
 *
 * @property {string} classification - Classification of the error type.
 * @property {object} [retryStrategy] - Suggested retry strategy.
 * @property {string} [explanation] - Human-readable explanation.
 * @property {string} [fallbackAction] - Suggested fallback action.
 * @property {number} confidence - Confidence score (0-1).
 * @property {boolean} [moderated] - Whether this was moderated/approved.
 */
interface IAISuggestions {
    /** Classification of the error type */
    readonly classification: string;
    /** Suggested retry strategy */
    readonly retryStrategy?: {
        readonly shouldRetry: boolean;
        readonly maxAttempts?: number;
        readonly baseDelayMs?: number;
        readonly backoffMultiplier?: number;
    };
    /** Human-readable explanation */
    readonly explanation?: string;
    /** Suggested fallback action */
    readonly fallbackAction?: string;
    /** Confidence score (0-1) */
    readonly confidence: number;
    /** Whether this was moderated/approved */
    readonly moderated?: boolean;
}
/**
 * Structured error information.
 *
 * @interface IErrorDetail
 *
 * @property {string} code - Error code for programmatic handling.
 * @property {string} message - Human-readable error message.
 * @property {Record<string, unknown>} [details] - Additional error context.
 * @property {number} timestamp - Unix timestamp when error occurred.
 * @property {string} [correlationId] - Optional correlation ID for tracing.
 * @property {IErrorDetail} [innerError] - Optional inner error for chained errors.
 * @property {string} [field] - Optional field name for validation errors.
 * @property {string} [resourceType] - Optional resource type for not found errors.
 * @property {string|number} [resourceId] - Optional resource ID for not found errors.
 * @property {IAISuggestions} [aiSuggestions] - AI suggestions if AI error engine is enabled.
 * @property {string} [auditId] - Audit trail ID for AI-modified errors.
 */
interface IErrorDetail {
    /** Error code for programmatic handling. */
    readonly code: string;
    /** Human-readable error message. */
    readonly message: string;
    /** Additional error context. */
    readonly details?: Record<string, unknown>;
    /** Unix timestamp when error occurred. */
    readonly timestamp: number;
    /** Optional correlation ID for request tracing */
    correlationId?: string;
    /** HTTP status code if applicable */
    httpStatus?: number;
    /** Original exception if available */
    exception?: unknown;
    /** Optional inner error for chained errors. */
    readonly innerError?: IErrorDetail;
    /** Optional field name for validation errors. */
    readonly field?: string;
    /** Optional resource type for not found errors. */
    readonly resourceType?: string;
    /** Optional resource identifier for not found errors. */
    readonly resourceId?: string | number;
    /** AI suggestions if AI error engine is enabled */
    readonly aiSuggestions?: IAISuggestions;
    /** Audit trail ID for AI-modified errors */
    readonly auditId?: string;
}
/**
 * @deprecated Use IErrorDetail instead.
 */
type ErrorDetail = IErrorDetail;
/**
 * @deprecated Use IAISuggestions instead.
 */
type AISuggestions = IAISuggestions;

/**
 * @fileoverview Result JSON Interface
 * @module @ark.alliance/core/result/interfaces/IResultJSON
 *
 * Defines the JSON serialization structure for Result objects.
 * Used for wire transfer and API responses.
 *
 * @author Armand Richelet-Kleinberg ; with Anthropic Claude Opus 4.5 model
 */

/**
 * JSON representation of a Result for serialization.
 *
 * @interface IResultJSON
 * @template T - The type of the success data.
 *
 * @property {boolean} success - Whether the operation was successful.
 * @property {string} status - The result status as a string.
 * @property {T} [data] - The success data if operation succeeded.
 * @property {IErrorDetail} [error] - Error details if operation failed.
 * @property {string} [reason] - Human-readable reason for the result.
 * @property {string} [correlationId] - Correlation ID for distributed tracing.
 * @property {number} timestamp - Unix timestamp when the result was created.
 * @property {number} [durationMs] - Duration of the operation in milliseconds.
 */
interface IResultJSON<T> {
    /** Whether the operation was successful. */
    readonly success: boolean;
    /** The result status as a string. */
    readonly status: string;
    /** The success data if operation succeeded. */
    readonly data?: T;
    /** Structured error details if operation failed. */
    readonly error?: IErrorDetail;
    /** Human-readable reason for the result. */
    readonly reason?: string;
    /** Correlation ID for distributed tracing. */
    readonly correlationId?: string;
    /** Unix timestamp when the result was created. */
    readonly timestamp: number;
    /** Duration of the operation in milliseconds. */
    readonly durationMs?: number;
}
/**
 * @deprecated Use IResultJSON instead.
 */
type ResultJSON<T> = IResultJSON<T>;

/**
 * @fileoverview Result Metrics Interface
 * @module @ark.alliance/core/result/interfaces/IResultMetrics
 *
 * Defines the metrics structure emitted by Result operations
 * for observability and monitoring purposes.
 *
 * @author Armand Richelet-Kleinberg ; with Anthropic Claude Opus 4.5 model
 */

/**
 * Metrics emitted by Result operations for observability.
 *
 * @interface IResultMetrics
 *
 * @property {ResultStatus} status - The result status of the operation.
 * @property {boolean} success - Whether the operation was successful.
 * @property {number} durationMs - Duration of the operation in milliseconds.
 * @property {string} [correlationId] - Optional correlation ID for distributed tracing.
 * @property {boolean} retryable - Whether the error is retryable.
 * @property {number} timestamp - Unix timestamp when the result was created.
 */
interface IResultMetrics {
    /** The result status of the operation. */
    readonly status: ResultStatus;
    /** Whether the operation was successful. */
    readonly success: boolean;
    /** Duration of the operation in milliseconds. */
    readonly durationMs: number;
    /** Optional correlation ID for distributed tracing. */
    readonly correlationId?: string;
    /** Whether the error is retryable. */
    readonly retryable: boolean;
    /** Unix timestamp when the result was created. */
    readonly timestamp: number;
}
/**
 * Type for metrics listener callback function.
 */
type MetricsListener = (metrics: IResultMetrics) => void;
/**
 * @deprecated Use IResultMetrics instead.
 */
type ResultMetrics = IResultMetrics;

/**
 * @fileoverview Result Logger Interface
 * @module @ark.alliance/core/result/interfaces/IResultLogger
 *
 * Logger interface for safe execution and result logging.
 * Allows integration with custom logging implementations.
 *
 * @author Armand Richelet-Kleinberg ; with Anthropic Claude Opus 4.5 model
 */
/**
 * Logger interface for safe execution functions.
 * Allows integration with custom logging implementations.
 *
 * @interface IResultLogger
 */
interface IResultLogger {
    /**
     * Logs a critical error.
     * @param message - Error message.
     * @param context - Additional context.
     */
    critical(message: string, context?: Record<string, unknown>): void;
    /**
     * Logs an error.
     * @param message - Error message.
     * @param context - Additional context.
     */
    error(message: string, context?: Record<string, unknown>): void;
    /**
     * Logs a warning.
     * @param message - Warning message.
     * @param context - Additional context.
     */
    warn(message: string, context?: Record<string, unknown>): void;
    /**
     * Logs an info message.
     * @param message - Info message.
     * @param context - Additional context.
     */
    info(message: string, context?: Record<string, unknown>): void;
    /**
     * Logs a debug message.
     * @param message - Debug message.
     * @param context - Additional context.
     */
    debug(message: string, context?: Record<string, unknown>): void;
}
/**
 * @deprecated Use IResultLogger instead.
 */
type ResultLogger = IResultLogger;

/**
 * @fileoverview Aggregated Error Detail Interface
 * @module @ark.alliance/core/result/interfaces/IAggregatedError
 *
 * Interface for errors that aggregate multiple error details.
 * Used by Result.combineAll() to collect all errors.
 *
 * @author Armand Richelet-Kleinberg ; with Anthropic Claude Opus 4.5 model
 */

/**
 * Error detail that contains multiple aggregated errors.
 *
 * @interface IAggregatedError
 * @extends {IErrorDetail}
 *
 * @remarks
 * Used when multiple operations fail and all errors need to be reported.
 * For example, batch validation where each item can have its own error.
 *
 * @example
 * ```typescript
 * const result = Result.combineAll([result1, result2, result3]);
 * if (result.isNotSuccess && isAggregatedError(result.error)) {
 *     for (const err of result.error.errors) {
 *         console.log(err.message);
 *     }
 * }
 * ```
 */
interface IAggregatedError extends IErrorDetail {
    /** Array of all individual errors. */
    readonly errors: readonly IErrorDetail[];
    /** Total count of errors. */
    readonly errorCount: number;
}
/**
 * Type guard to check if an error is an aggregated error.
 *
 * @param error - The error to check.
 * @returns True if error is an IAggregatedError.
 */
declare function isAggregatedError(error: IErrorDetail | undefined): error is IAggregatedError;

/**
 * @fileoverview Retry Options Interface
 * @module @ark.alliance/core/result/interfaces/IRetryOptions
 *
 * Configuration options for the retryWithResult utility.
 *
 * @author Armand Richelet-Kleinberg ; with Anthropic Claude Opus 4.5 model
 */

/**
 * Configuration options for retry operations.
 *
 * @interface IRetryOptions
 *
 * @example
 * ```typescript
 * const result = await retryWithResult(
 *     () => fetchData(),
 *     {
 *         maxAttempts: 5,
 *         baseDelayMs: 200,
 *         onRetry: (attempt, error) => console.log(`Retry ${attempt}: ${error.message}`)
 *     }
 * );
 * ```
 */
interface IRetryOptions {
    /**
     * Maximum number of attempts (including the first).
     * @default 3
     */
    readonly maxAttempts?: number;
    /**
     * Base delay between retries in milliseconds.
     * @default 100
     */
    readonly baseDelayMs?: number;
    /**
     * Maximum delay between retries in milliseconds.
     * @default 30000
     */
    readonly maxDelayMs?: number;
    /**
     * Multiplier for exponential backoff.
     * @default 2
     */
    readonly backoffMultiplier?: number;
    /**
     * Jitter factor (0-1) to add randomness to delays.
     * @default 0.1
     */
    readonly jitterFactor?: number;
    /**
     * Optional callback invoked before each retry.
     *
     * @param attempt - The attempt number (1-based, first retry is 2).
     * @param error - The error from the previous attempt.
     * @param delayMs - The delay before the next attempt.
     */
    readonly onRetry?: (attempt: number, error: IErrorDetail, delayMs: number) => void;
}
/**
 * Default retry options.
 */
declare const DefaultRetryOptions: Required<Omit<IRetryOptions, 'onRetry'>>;

/**
 * @fileoverview Pagination Value Object
 * @module @ark.alliance/core/result/value-objects/PaginationInfo
 *
 * Immutable value object representing pagination metadata.
 * Used for paginated API responses.
 *
 * @author Armand Richelet-Kleinberg ; with Anthropic Claude Opus 4.5 model
 */
/**
 * Immutable value object representing pagination metadata.
 *
 * @class PaginationInfo
 *
 * @remarks
 * This is a value object in DDD terms - it is defined by its attributes
 * and has no conceptual identity. Two PaginationInfo instances with the
 * same values are considered equal.
 */
declare class PaginationInfo {
    /**
     * Current page number (1-indexed).
     * @readonly
     */
    readonly page: number;
    /**
     * Number of items per page.
     * @readonly
     */
    readonly pageSize: number;
    /**
     * Total number of items across all pages.
     * @readonly
     */
    readonly totalItems: number;
    /**
     * Total number of pages.
     * @readonly
     */
    readonly totalPages: number;
    /**
     * Whether there is a next page.
     * @readonly
     */
    readonly hasNextPage: boolean;
    /**
     * Whether there is a previous page.
     * @readonly
     */
    readonly hasPreviousPage: boolean;
    /**
     * Creates a new PaginationInfo instance.
     *
     * @param page - Current page number (1-indexed).
     * @param pageSize - Number of items per page.
     * @param totalItems - Total number of items across all pages.
     * @private
     */
    private constructor();
    /**
     * Creates a new PaginationInfo from parameters.
     *
     * @param page - Current page number (1-indexed).
     * @param pageSize - Items per page.
     * @param totalItems - Total items across all pages.
     * @returns New PaginationInfo instance.
     */
    static create(page: number, pageSize: number, totalItems: number): PaginationInfo;
    /**
     * Creates an empty PaginationInfo (no items).
     *
     * @param pageSize - Items per page (default: 10).
     * @returns Empty PaginationInfo.
     */
    static empty(pageSize?: number): PaginationInfo;
    /**
     * Creates PaginationInfo from offset-based pagination.
     *
     * @param offset - Number of items to skip.
     * @param limit - Number of items per page.
     * @param totalItems - Total items.
     * @returns PaginationInfo with calculated page.
     */
    static fromOffset(offset: number, limit: number, totalItems: number): PaginationInfo;
    /**
     * Gets the offset for database queries.
     * @returns Number of items to skip.
     */
    get offset(): number;
    /**
     * Gets the limit for database queries.
     * @returns Number of items to take.
     */
    get limit(): number;
    /**
     * Gets the first item number on the current page (1-indexed).
     * @returns First item number.
     */
    get firstItem(): number;
    /**
     * Gets the last item number on the current page (1-indexed).
     * @returns Last item number.
     */
    get lastItem(): number;
    /**
     * Whether there are any items.
     * @returns True if totalItems > 0.
     */
    get hasItems(): boolean;
    /**
     * Gets pagination for next page.
     * @returns PaginationInfo for next page or this if no next page.
     */
    nextPage(): PaginationInfo;
    /**
     * Gets pagination for previous page.
     * @returns PaginationInfo for previous page or this if no previous page.
     */
    previousPage(): PaginationInfo;
    /**
     * Gets pagination for first page.
     * @returns PaginationInfo for first page.
     */
    firstPage(): PaginationInfo;
    /**
     * Gets pagination for last page.
     * @returns PaginationInfo for last page.
     */
    lastPage(): PaginationInfo;
    /**
     * Gets pagination for a specific page.
     * @param page - Target page number.
     * @returns PaginationInfo for specified page, clamped to valid range.
     */
    goToPage(page: number): PaginationInfo;
    /**
     * Converts to plain object.
     * @returns Plain object representation.
     */
    toJSON(): IPaginationInfoDTO;
    /**
     * Creates from plain object.
     * @param dto - Plain object representation.
     * @returns PaginationInfo instance.
     */
    static fromJSON(dto: IPaginationInfoDTO): PaginationInfo;
    /**
     * Checks equality with another PaginationInfo.
     * @param other - PaginationInfo to compare.
     * @returns True if all values are equal.
     */
    equals(other: PaginationInfo): boolean;
    /**
     * String representation.
     * @returns Formatted string.
     */
    toString(): string;
}
/**
 * Data Transfer Object for PaginationInfo serialization.
 *
 * @interface IPaginationInfoDTO
 */
interface IPaginationInfoDTO {
    readonly page: number;
    readonly pageSize: number;
    readonly totalItems: number;
    readonly totalPages: number;
    readonly hasNextPage: boolean;
    readonly hasPreviousPage: boolean;
}

/**
 * @fileoverview Result Exception Class
 * @module @ark.alliance/core/result/exceptions/ResultException
 *
 * Exception class created from a failed Result.
 * Preserves Result information for debugging and error handling.
 *
 * @author Armand Richelet-Kleinberg ; with Anthropic Claude Opus 4.5 model
 */

/**
 * Exception class created from a failed Result.
 *
 * @extends Error
 *
 * @remarks
 * This class extends the native Error class and preserves all Result information
 * for proper debugging and error handling in catch blocks.
 */
declare class ResultException extends Error {
    /**
     * Unique identifier for this error type.
     * @readonly
     */
    readonly name = "ResultException";
    /**
     * The result status that caused this exception.
     * @readonly
     */
    readonly status: ResultStatus;
    /**
     * The reason/message for the failure.
     * @readonly
     */
    readonly reason?: string;
    /**
     * Structured error details.
     * @readonly
     */
    readonly errorDetail?: IErrorDetail;
    /**
     * The original exception if this was caused by an unexpected error.
     * @readonly
     */
    readonly innerError?: Error;
    /**
     * Additional data associated with the result.
     * @readonly
     */
    readonly data?: unknown;
    /**
     * Correlation ID for tracing.
     * @readonly
     */
    readonly correlationId?: string;
    /**
     * Creates a new ResultException.
     *
     * @param status - The result status that caused this exception.
     * @param error - Optional structured error details.
     * @param innerError - Optional inner exception that caused this error.
     * @param data - Optional additional data associated with the result.
     */
    constructor(status: ResultStatus, error?: IErrorDetail, innerError?: Error, data?: unknown);
    /**
     * Creates a ResultException from an unexpected error.
     *
     * @param error - The original error that occurred.
     * @param correlationId - Optional correlation ID for tracing.
     * @returns New ResultException with UNEXPECTED status.
     */
    static fromError(error: Error, correlationId?: string): ResultException;
    /**
     * Creates a not found exception.
     *
     * @param resourceType - Type of resource that was not found.
     * @param identifier - Identifier of the resource.
     * @param correlationId - Optional correlation ID for tracing.
     * @returns New ResultException with NOT_FOUND status.
     */
    static notFound(resourceType: string, identifier: string | number, correlationId?: string): ResultException;
    /**
     * Creates a validation exception.
     *
     * @param message - Validation error message.
     * @param details - Optional validation details.
     * @param correlationId - Optional correlation ID for tracing.
     * @returns New ResultException with VALIDATION_ERROR status.
     */
    static validationError(message: string, details?: Record<string, unknown>, correlationId?: string): ResultException;
    /**
     * Creates an unauthorized exception.
     *
     * @param message - Optional custom message.
     * @param correlationId - Optional correlation ID for tracing.
     * @returns New ResultException with UNAUTHORIZED status.
     */
    static unauthorized(message?: string, correlationId?: string): ResultException;
    /**
     * Creates a forbidden exception.
     *
     * @param message - Optional custom message.
     * @param correlationId - Optional correlation ID for tracing.
     * @returns New ResultException with FORBIDDEN status.
     */
    static forbidden(message?: string, correlationId?: string): ResultException;
    /**
     * Creates a timeout exception.
     *
     * @param operation - Name of the operation that timed out.
     * @param timeoutMs - Timeout duration in milliseconds.
     * @param correlationId - Optional correlation ID for tracing.
     * @returns New ResultException with TIMEOUT status.
     */
    static timeout(operation: string, timeoutMs: number, correlationId?: string): ResultException;
    /**
     * Type guard to check if an error is a ResultException.
     *
     * @param error - Error to check.
     * @returns True if error is a ResultException.
     */
    static isResultException(error: unknown): error is ResultException;
    /**
     * Gets the full error chain as a string.
     *
     * @returns Formatted error chain including inner errors.
     */
    getFullMessage(): string;
    /**
     * Converts to a plain object for serialization.
     *
     * @returns Plain object representation suitable for JSON serialization.
     */
    toJSON(): Record<string, unknown>;
    toString(): string;
}

/**
 * @fileoverview Generic Result Entity
 * @module @ark.alliance/core/result/entities/Result
 *
 * Type-safe result pattern for operation outcomes.
 * Provides consistent error handling across the application.
 *
 * @remarks
 * Key features:
 * - **Static shortcuts**: Result.Success, Result.Failure, etc.
 * - **Fluent methods**: withReason(), withData(), withStatus()
 * - **Railway pattern**: whenSuccess(), map(), flatMap()
 * - **Exception conversion**: toException()
 * - **AI Enhancement**: Optional AI-powered error analysis
 * - **Metrics emission**: Observable for monitoring
 *
 * @author Armand Richelet-Kleinberg ; with Anthropic Claude Opus 4.5 model
 */

/**
 * Registers a metrics listener for all Result operations.
 *
 * @param listener - Callback to receive metrics.
 * @returns Unsubscribe function.
 */
declare function onResultMetrics(listener: MetricsListener): () => void;
/**
 * Generic Result entity for type-safe operation outcomes.
 *
 * @template T - The type of the success data.
 *
 * @example
 * ```typescript
 * // Success result
 * const success = Result.ok({ id: 1, name: 'Test' });
 *
 * // Failure result
 * const failure = Result.fail<User>({ code: 'NOT_FOUND', message: 'User not found', timestamp: Date.now() });
 *
 * // Static shortcuts
 * const notFound = Result.NotFound.withReason('User 123 not found');
 *
 * // Railway-oriented programming
 * const result = await validateUser(input)
 *     .whenSuccess(createUser)
 *     .whenSuccess(sendWelcomeEmail);
 * ```
 */
declare class Result<T> {
    /** Whether the operation was successful. */
    readonly success: boolean;
    /** The result status. */
    readonly status: ResultStatus;
    /** The success data (only present if success is true). */
    readonly data?: T;
    /** Error information (only present if success is false). */
    readonly error?: IErrorDetail;
    /** The reason in text why a not succeeded result occurred. */
    readonly reason?: string;
    /** Optional correlation ID for tracing. */
    readonly correlationId?: string;
    /** Timestamp when the result was created. */
    readonly timestamp: number;
    /** The original exception if unexpected error. */
    readonly exception?: Error;
    /** Duration of the operation in milliseconds (if tracked). */
    readonly durationMs?: number;
    private constructor();
    /** Creates a successful void result. */
    static get Success(): Result<void>;
    /** Creates a failed void result. */
    static get Failure(): Result<void>;
    /** Creates an unexpected error void result. */
    static get Unexpected(): Result<void>;
    /** Creates an unauthorized void result. */
    static get Unauthorized(): Result<void>;
    /** Creates a forbidden void result. */
    static get Forbidden(): Result<void>;
    /** Creates an already-completed void result. */
    static get Already(): Result<void>;
    /** Creates a not found void result. */
    static get NotFound(): Result<void>;
    /** Creates a bad prerequisites void result. */
    static get BadPrerequisites(): Result<void>;
    /** Creates a bad parameters void result. */
    static get BadParameters(): Result<void>;
    /** Creates a cancelled void result. */
    static get Cancelled(): Result<void>;
    /** Creates a timeout void result. */
    static get Timeout(): Result<void>;
    /** Creates a no connection void result. */
    static get NoConnection(): Result<void>;
    /** Creates a not implemented void result. */
    static get NotImplemented(): Result<void>;
    /** Creates a rate limited void result. */
    static get RateLimited(): Result<void>;
    /** Creates a circuit open void result. */
    static get CircuitOpen(): Result<void>;
    /** Creates a bulkhead rejected void result. */
    static get BulkheadRejected(): Result<void>;
    /**
     * Creates a successful result with data.
     *
     * @param data - The success data.
     * @param correlationId - Optional correlation ID.
     * @param durationMs - Optional operation duration.
     * @returns New success Result.
     */
    static ok<T>(data: T, correlationId?: string, durationMs?: number): Result<T>;
    /**
     * Creates a failed result with error details.
     *
     * @param error - Error details.
     * @param status - Result status (default: FAILURE).
     * @returns New failure Result.
     */
    static fail<T>(error: IErrorDetail, status?: ResultStatus): Result<T>;
    /**
     * Creates a failed result from an Error object.
     *
     * @param error - The error object.
     * @param code - Optional error code.
     * @param correlationId - Optional correlation ID.
     * @returns New failure Result with UNEXPECTED status.
     */
    static fromError<T>(error: Error, code?: string, correlationId?: string): Result<T>;
    /**
     * Creates a Result from another Result (copy constructor).
     *
     * @param result - Source result.
     * @returns New Result with same properties.
     */
    static from<T>(result: Result<T>): Result<T>;
    /**
     * Wraps an async operation and converts exceptions to Results.
     *
     * @param action - The async action to execute.
     * @param correlationId - Optional correlation ID.
     * @returns Promise of Result.
     */
    static tryAsync<T>(action: () => Promise<T>, correlationId?: string): Promise<Result<T>>;
    /**
     * Wraps a sync operation and converts exceptions to Results.
     *
     * @param action - The sync action to execute.
     * @param correlationId - Optional correlation ID.
     * @returns Result.
     */
    static try<T>(action: () => T, correlationId?: string): Result<T>;
    /**
     * Creates a successful result with data.
     * Alias for Result.ok() for backward compatibility.
     *
     * @param data - The success data.
     * @param correlationId - Optional correlation ID.
     * @returns New success Result.
     */
    static success<T>(data: T, correlationId?: string): Result<T>;
    /**
     * Creates a failed result.
     * Alias for Result.fail()/fromError() for backward compatibility.
     *
     * @param error - Error object, string message, or error details.
     * @returns New failure Result.
     */
    static failure<T>(error: Error | string | IErrorDetail): Result<T>;
    /**
     * Creates a bad parameters failure with the specified type.
     * Use this instead of Result.BadParameters.withReason() for proper typing.
     *
     * @param reason - The error reason message.
     * @returns New failure Result with BAD_PARAMETERS status.
     *
     * @example
     * ```typescript
     * function divide(a: number, b: number): Result<number> {
     *     if (b === 0) {
     *         return Result.badParameters('Cannot divide by zero');
     *     }
     *     return Result.ok(a / b);
     * }
     * ```
     */
    static badParameters<T>(reason: string): Result<T>;
    /**
     * Creates a not found failure with the specified type.
     *
     * @param reason - The error reason message.
     * @returns New failure Result with NOT_FOUND status.
     */
    static notFound<T>(reason: string): Result<T>;
    /**
     * Creates an unauthorized failure with the specified type.
     *
     * @param reason - The error reason message.
     * @returns New failure Result with UNAUTHORIZED status.
     */
    static unauthorized<T>(reason: string): Result<T>;
    /**
     * Creates a bad prerequisites failure with the specified type.
     *
     * @param reason - The error reason message.
     * @returns New failure Result with BAD_PREREQUISITES status.
     */
    static badPrerequisites<T>(reason: string): Result<T>;
    /**
     * Creates an unexpected error failure with the specified type.
     *
     * @param reason - The error reason message.
     * @returns New failure Result with UNEXPECTED status.
     */
    static unexpected<T>(reason: string): Result<T>;
    /**
     * Combines multiple results into a single result containing an array.
     * If any result is a failure, returns the first failure.
     *
     * @param results - Array of results to combine.
     * @returns Combined Result with array of values, or first failure.
     */
    static combine<T>(results: Result<T>[]): Result<T[]>;
    /**
     * Combines multiple results, collecting ALL errors instead of stopping at first.
     * Useful for batch validation where all errors should be reported.
     *
     * @param results - Array of results to combine.
     * @returns Combined Result with array of values, or aggregated failure.
     *
     * @example
     * ```typescript
     * const results = [validateName(input), validateEmail(input), validateAge(input)];
     * const combined = Result.combineAll(results);
     * if (combined.isNotSuccess) {
     *     // combined.error.details.errors contains all individual errors
     *     console.log(`${combined.error.details.errorCount} validation errors`);
     * }
     * ```
     */
    static combineAll<T>(results: Result<T>[]): Result<T[]>;
    /**
     * Creates a Result from a nullable value.
     * Returns success if value is not null/undefined, failure otherwise.
     *
     * @param value - The possibly null/undefined value.
     * @param errorMessage - Error message if value is null/undefined.
     * @returns Success Result with value, or failure Result.
     */
    static fromNullable<T>(value: T | null | undefined, errorMessage: string): Result<T>;
    /**
     * Creates a Result from a Promise.
     * Resolves to success if promise resolves, failure if it rejects.
     *
     * @param promise - The promise to convert.
     * @returns Promise resolving to Result.
     */
    static fromPromise<T>(promise: Promise<T>): Promise<Result<T>>;
    get isSuccess(): boolean;
    get isNotSuccess(): boolean;
    get isFailure(): boolean;
    get isUnexpected(): boolean;
    get isUnauthorized(): boolean;
    get isForbidden(): boolean;
    get isAlready(): boolean;
    get isNotFound(): boolean;
    get isBadPrerequisites(): boolean;
    get isBadParameters(): boolean;
    get isCancelled(): boolean;
    get isTimeout(): boolean;
    get isNoConnection(): boolean;
    get isNotImplemented(): boolean;
    get isRateLimited(): boolean;
    get isCircuitOpen(): boolean;
    get isBulkheadRejected(): boolean;
    get isRetryable(): boolean;
    get hasData(): boolean;
    get httpStatusCode(): number;
    withReason(reason: string): Result<T>;
    addReason(reason: string): Result<T>;
    withStatus(status: ResultStatus): Result<T>;
    withData<U>(data: U): Result<U>;
    withException(exception: Error): Result<T>;
    withCorrelationId(correlationId: string): Result<T>;
    withError(error: IErrorDetail): Result<T>;
    whenSuccess<U>(fn: (result: Result<T>) => Result<U>): Result<U>;
    whenSuccessAsync<U>(fn: (result: Result<T>) => Promise<Result<U>>): Promise<Result<U>>;
    onFailure(fn: (result: Result<T>) => void): Result<T>;
    onSuccess(fn: (data: T) => void): Result<T>;
    map<U>(mapper: (data: T) => U): Result<U>;
    mapAsync<U>(mapper: (data: T) => Promise<U>): Promise<Result<U>>;
    flatMap<U>(mapper: (data: T) => Result<U>): Result<U>;
    flatMapAsync<U>(mapper: (data: T) => Promise<Result<U>>): Promise<Result<U>>;
    match<U>(onSuccess: (data: T) => U, onFailure: (error: IErrorDetail) => U): U;
    getOrThrow(): T;
    getOrDefault(defaultValue: T): T;
    getOrNull(): T | null;
    getOrElse(factory: () => T): T;
    /**
     * Gets the success data.
     * Alias for 'data' property for backward compatibility.
     *
     * @returns The data value, or undefined if failure.
     */
    get value(): T | undefined;
    /**
     * Gets the success data or throws if failure.
     * Alias for getOrThrow() for backward compatibility.
     *
     * @returns The data value.
     * @throws ResultException if result is not successful or data is undefined.
     */
    getValue(): T;
    /**
     * Gets the success data or returns default value.
     * Alias for getOrDefault() for backward compatibility.
     *
     * @param defaultValue - Value to return if failure.
     * @returns The data value or default.
     */
    getValueOrDefault(defaultValue: T): T;
    /**
     * Gets the error or null if successful.
     * Alias for error property for backward compatibility.
     *
     * @returns The error detail or null.
     */
    getError(): IErrorDetail | null;
    /**
     * Folds the result into a single value.
     * Alias for match() for backward compatibility.
     *
     * @param onSuccess - Function to apply if successful.
     * @param onFailure - Function to apply if failed.
     * @returns The result of the applied function.
     */
    fold<U>(onSuccess: (data: T) => U, onFailure: (error: IErrorDetail) => U): U;
    /**
     * Executes a side effect on success.
     * Alias for onSuccess() for backward compatibility.
     *
     * @param fn - Function to execute with the data.
     * @returns This result for chaining.
     */
    tap(fn: (data: T) => void): Result<T>;
    /**
     * Executes a side effect on failure.
     *
     * @param fn - Function to execute with the error.
     * @returns This result for chaining.
     */
    tapError(fn: (error: IErrorDetail) => void): Result<T>;
    /**
     * Maps the error to a different error.
     *
     * @param mapper - Error transformation function.
     * @returns Result with mapped error, or unchanged if successful.
     */
    mapError(mapper: (error: IErrorDetail) => IErrorDetail): Result<T>;
    /**
     * Combines this result with another using a combiner function.
     *
     * @param other - The other result to combine with.
     * @param combiner - Function to combine the two values.
     * @returns Combined result, or first failure encountered.
     */
    combineWith<U, V>(other: Result<U>, combiner: (a: T, b: U) => V): Result<V>;
    toException(): ResultException;
    toVoid(): Result<void>;
    toJSON(): IResultJSON<T>;
    static fromJSON<T>(json: IResultJSON<T>): Result<T>;
    toString(): string;
}
/**
 * @deprecated Use Result<T> directly.
 */
type ServiceResult<T> = Result<T>;
/**
 * @deprecated Use Result.ok() instead.
 */
declare function successResult<T>(data: T): Result<T>;
/**
 * @deprecated Use Result.fail() instead.
 */
declare function errorResult<T>(code: string, message: string, details?: unknown): Result<T>;

/**
 * @fileoverview Paged Result Entity
 * @module @ark.alliance/core/result/entities/PagedResult
 *
 * Extended Result entity for paginated data responses.
 * Uses composition pattern for proper TypeScript extension.
 *
 * @author Armand Richelet-Kleinberg ; with Anthropic Claude Opus 4.5 model
 */

/**
 * JSON representation of a PagedResult for serialization.
 *
 * @interface IPagedResultJSON
 * @template T - The type of items in the page.
 * @extends {IResultJSON<T[]>}
 */
interface IPagedResultJSON<T> extends IResultJSON<T[]> {
    /** Pagination metadata. */
    readonly pagination?: IPaginationInfoDTO;
}
/**
 * Result entity for paginated data.
 * Uses composition to wrap a Result<T[]> with pagination metadata.
 *
 * @template T - The type of items in the page.
 */
declare class PagedResult<T> {
    /**
     * The underlying Result.
     * @private
     */
    private readonly _result;
    /**
     * Pagination metadata.
     * @readonly
     */
    readonly pagination?: PaginationInfo;
    /**
     * Creates a new PagedResult.
     *
     * @param result - The underlying Result containing the array of items.
     * @param pagination - Optional pagination metadata.
     * @private
     */
    private constructor();
    get success(): boolean;
    get status(): ResultStatus;
    get data(): T[] | undefined;
    get error(): IErrorDetail | undefined;
    get reason(): string | undefined;
    get correlationId(): string | undefined;
    get timestamp(): number;
    get isSuccess(): boolean;
    get isNotSuccess(): boolean;
    get hasData(): boolean;
    get count(): number;
    get isEmpty(): boolean;
    /**
     * Creates a successful paged result.
     *
     * @param data - Array of items for the current page.
     * @param pagination - Pagination metadata.
     * @param correlationId - Optional correlation ID for tracing.
     * @returns New successful PagedResult.
     */
    static ok<T>(data: T[], pagination: PaginationInfo, correlationId?: string): PagedResult<T>;
    /**
     * Creates a successful paged result with calculated pagination.
     *
     * @param data - Array of items for the current page.
     * @param page - Current page number (1-indexed).
     * @param pageSize - Items per page.
     * @param totalItems - Total items across all pages.
     * @param correlationId - Optional correlation ID for tracing.
     * @returns New successful PagedResult with calculated pagination.
     */
    static okWithPagination<T>(data: T[], page: number, pageSize: number, totalItems: number, correlationId?: string): PagedResult<T>;
    /**
     * Creates an empty successful paged result.
     *
     * @param page - Current page number (default: 1).
     * @param pageSize - Items per page (default: 10).
     * @param correlationId - Optional correlation ID for tracing.
     * @returns Empty PagedResult.
     */
    static empty<T>(page?: number, pageSize?: number, correlationId?: string): PagedResult<T>;
    /**
     * Creates a failed paged result.
     *
     * @param error - Error details.
     * @param status - Result status (default: FAILURE).
     * @returns New failed PagedResult.
     */
    static fail<T>(error: IErrorDetail, status?: ResultStatus): PagedResult<T>;
    /**
     * Creates a PagedResult from an existing Result<T[]>.
     *
     * @param result - Existing array result.
     * @param pagination - Optional pagination metadata.
     * @returns New PagedResult wrapping the result.
     */
    static fromResult<T>(result: Result<T[]>, pagination?: PaginationInfo): PagedResult<T>;
    getOrThrow(): T[];
    getOrDefault(defaultValue: T[]): T[];
    getOrEmpty(): T[];
    map<U>(mapper: (item: T) => U): PagedResult<U>;
    filter(predicate: (item: T) => boolean): PagedResult<T>;
    toResult(): Result<T[]>;
    toVoid(): Result<void>;
    toJSON(): IPagedResultJSON<T>;
    static fromJSON<T>(json: IPagedResultJSON<T>): PagedResult<T>;
    toString(): string;
}
/**
 * @deprecated Use IPagedResultJSON instead.
 */
type PagedResultJSON<T> = IPagedResultJSON<T>;

/**
 * @fileoverview Exception DTO
 * @module @ark.alliance/core/result/dtos/ExceptionDto
 *
 * Serializable exception information for API responses.
 *
 * @author Armand Richelet-Kleinberg ; with Anthropic Claude Opus 4.5 model
 */
/**
 * Serializable exception information for API responses.
 *
 * @interface IExceptionDto
 *
 * @property {string} name - Exception type name.
 * @property {string} message - Exception message.
 * @property {string} [stack] - Stack trace (development only).
 * @property {IExceptionDto} [innerException] - Nested exception if any.
 */
interface IExceptionDto {
    /**
     * Exception type name.
     * E.g., 'TypeError', 'Error', 'ResultException'.
     */
    readonly name: string;
    /**
     * Exception message.
     * Human-readable description of what went wrong.
     */
    readonly message: string;
    /**
     * Stack trace (may be omitted in production).
     * Only included when includeStack option is true.
     */
    readonly stack?: string;
    /**
     * Inner exception if any.
     * For chained exceptions.
     */
    readonly innerException?: IExceptionDto;
}
/**
 * Converts an Error to IExceptionDto.
 *
 * @param error - The error to convert.
 * @param includeStack - Whether to include stack trace.
 * @returns IExceptionDto representation.
 */
declare function toExceptionDto(error: Error, includeStack?: boolean): IExceptionDto;
/**
 * @deprecated Use IExceptionDto instead.
 */
type ExceptionDto = IExceptionDto;

/**
 * @fileoverview Result DTO
 * @module @ark.alliance/core/result/dtos/ResultDto
 *
 * Data Transfer Object for serializing Results in API responses.
 *
 * @author Armand Richelet-Kleinberg ; with Anthropic Claude Opus 4.5 model
 */

/**
 * Base DTO fields for all Result DTOs.
 *
 * @interface IResultDtoBase
 */
interface IResultDtoBase {
    /** The result status. */
    readonly status: ResultStatus;
    /** The reason for failure if not successful. */
    readonly reason?: string;
    /** Error code for programmatic handling. */
    readonly code?: string;
    /** Exception details if unexpected error. */
    readonly exception?: IExceptionDto;
    /** Correlation ID for tracing. */
    readonly correlationId?: string;
    /** Timestamp of the result. */
    readonly timestamp: number;
}
/**
 * DTO for void Result (no data).
 */
type IVoidResultDto = IResultDtoBase;
/**
 * DTO for Result with data.
 *
 * @interface IResultDto
 * @template T - Type of the data.
 * @extends {IResultDtoBase}
 */
interface IResultDto<T> extends IResultDtoBase {
    /** The data if successful. */
    readonly data?: T;
}
/**
 * Complete API response structure with HTTP status code.
 *
 * @interface IApiResponse
 * @template T - Type of the data.
 */
interface IApiResponse<T> {
    /** HTTP status code to return. */
    readonly statusCode: number;
    /** Response body. */
    readonly body: IResultDto<T>;
}
/**
 * Converts a Result<T> to IResultDto<T>.
 *
 * @template T - Type of the data.
 * @param result - The Result to convert.
 * @param includeStack - Whether to include stack trace in exception.
 * @returns IResultDto<T> representation.
 */
declare function toResultDto<T>(result: Result<T>, includeStack?: boolean): IResultDto<T>;
/**
 * Gets HTTP status code for a Result.
 *
 * @template T - Type of the data.
 * @param result - The result to check.
 * @returns Appropriate HTTP status code.
 */
declare function getHttpStatusCode<T>(result: Result<T>): number;
/**
 * Creates an API response object from a Result.
 *
 * @template T - Type of the data.
 * @param result - The result to convert.
 * @param includeStack - Whether to include stack traces (dev mode).
 * @returns Object with status code and body.
 */
declare function createApiResponse<T>(result: Result<T>, includeStack?: boolean): IApiResponse<T>;
/**
 * @deprecated Use IResultDtoBase instead.
 */
type ResultDtoBase = IResultDtoBase;
/**
 * @deprecated Use IVoidResultDto instead.
 */
type VoidResultDto = IVoidResultDto;
/**
 * @deprecated Use IResultDto instead.
 */
type ResultDto<T> = IResultDto<T>;
/**
 * @deprecated Use IApiResponse instead.
 */
type ApiResponse<T> = IApiResponse<T>;

/**
 * @fileoverview Paged Result DTO
 * @module @ark.alliance/core/result/dtos/PagedResultDto
 *
 * Data Transfer Object for serializing PagedResults in API responses.
 *
 * @author Armand Richelet-Kleinberg ; with Anthropic Claude Opus 4.5 model
 */

/**
 * DTO for paginated results.
 *
 * @interface IPagedResultDto
 * @template T - Type of items in the page.
 * @extends {IResultDto<T[]>}
 */
interface IPagedResultDto<T> extends IResultDto<T[]> {
    /** Pagination metadata. */
    readonly pagination?: IPaginationInfoDTO;
}
/**
 * Converts a PagedResult to IPagedResultDto.
 *
 * @template T - Type of items.
 * @param result - The PagedResult to convert.
 * @param includeStack - Whether to include stack trace.
 * @returns IPagedResultDto representation.
 */
declare function toPagedResultDto<T>(result: PagedResult<T>, includeStack?: boolean): IPagedResultDto<T>;
/**
 * Creates a PagedResult from IPagedResultDto.
 *
 * @template T - Type of items.
 * @param dto - The DTO to convert.
 * @returns PagedResult instance.
 */
declare function fromPagedResultDto<T>(dto: IPagedResultDto<T>): PagedResult<T>;
/**
 * Creates an API response for a PagedResult.
 *
 * @template T - Type of items.
 * @param result - The PagedResult to convert.
 * @param includeStack - Whether to include stack traces (dev mode).
 * @returns Object with status code and body including pagination.
 */
declare function createPagedApiResponse<T>(result: PagedResult<T>, includeStack?: boolean): {
    statusCode: number;
    body: IPagedResultDto<T>;
};
/**
 * @deprecated Use IPagedResultDto instead.
 */
type PagedResultDto<T> = IPagedResultDto<T>;

/**
 * @fileoverview Error Detail Factory
 * @module @ark.alliance/core/result/utilities/ErrorDetailFactory
 *
 * Factory functions for creating structured error details.
 *
 * @author Armand Richelet-Kleinberg ; with Anthropic Claude Opus 4.5 model
 */

/**
 * Creates an IErrorDetail from an Error object.
 *
 * @param error - The error to convert.
 * @param code - Optional error code (defaults to 'UNKNOWN_ERROR').
 * @param correlationId - Optional correlation ID for tracing.
 * @returns Structured IErrorDetail.
 */
declare function createErrorDetail(error: Error, code?: string, correlationId?: string): IErrorDetail;
/**
 * Creates a validation error detail.
 *
 * @param field - The field that failed validation.
 * @param message - Validation error message.
 * @param value - Optional invalid value.
 * @param correlationId - Optional correlation ID.
 * @returns Validation IErrorDetail.
 */
declare function createValidationError(field: string, message: string, value?: unknown, correlationId?: string): IErrorDetail;
/**
 * Creates a not found error detail.
 *
 * @param resourceType - Type of resource not found.
 * @param identifier - Resource identifier.
 * @param correlationId - Optional correlation ID.
 * @returns Not found IErrorDetail.
 */
declare function createNotFoundError(resourceType: string, identifier: string | number, correlationId?: string): IErrorDetail;
/**
 * Creates a timeout error detail.
 *
 * @param operation - Name of the operation that timed out.
 * @param timeoutMs - Timeout duration in milliseconds.
 * @param correlationId - Optional correlation ID.
 * @returns Timeout IErrorDetail.
 */
declare function createTimeoutError(operation: string, timeoutMs: number, correlationId?: string): IErrorDetail;
/**
 * Creates a rate limited error detail.
 *
 * @param limit - The rate limit that was exceeded.
 * @param windowMs - The rate limit window in milliseconds.
 * @param retryAfterMs - Suggested retry delay in milliseconds.
 * @param correlationId - Optional correlation ID.
 * @returns Rate limited IErrorDetail.
 */
declare function createRateLimitedError(limit: number, windowMs: number, retryAfterMs: number, correlationId?: string): IErrorDetail;
/**
 * Creates a circuit breaker open error detail.
 *
 * @param circuitName - Name of the circuit that is open.
 * @param resetTimeMs - Time until circuit may reset.
 * @param correlationId - Optional correlation ID.
 * @returns Circuit open IErrorDetail.
 */
declare function createCircuitOpenError(circuitName: string, resetTimeMs: number, correlationId?: string): IErrorDetail;
/**
 * Creates a bulkhead rejected error detail.
 *
 * @param bulkheadName - Name of the bulkhead.
 * @param maxConcurrent - Maximum concurrent requests allowed.
 * @param correlationId - Optional correlation ID.
 * @returns Bulkhead rejected IErrorDetail.
 */
declare function createBulkheadRejectedError(bulkheadName: string, maxConcurrent: number, correlationId?: string): IErrorDetail;
/**
 * Creates an unauthorized error detail.
 *
 * @param reason - Reason for unauthorized access.
 * @param correlationId - Optional correlation ID.
 * @returns Unauthorized IErrorDetail.
 */
declare function createUnauthorizedError(reason?: string, correlationId?: string): IErrorDetail;
/**
 * Creates a forbidden error detail.
 *
 * @param resource - Resource that access was denied to.
 * @param action - Action that was denied.
 * @param correlationId - Optional correlation ID.
 * @returns Forbidden IErrorDetail.
 */
declare function createForbiddenError(resource: string, action: string, correlationId?: string): IErrorDetail;
/**
 * Creates a conflict error detail.
 *
 * @param resourceType - Type of resource in conflict.
 * @param identifier - Resource identifier.
 * @param reason - Reason for conflict.
 * @param correlationId - Optional correlation ID.
 * @returns Conflict IErrorDetail.
 */
declare function createConflictError(resourceType: string, identifier: string | number, reason: string, correlationId?: string): IErrorDetail;
/**
 * Chains an inner error to an error detail.
 *
 * @param error - The outer error detail.
 * @param innerError - The inner error detail to chain.
 * @returns New IErrorDetail with inner error attached.
 */
declare function chainError(error: IErrorDetail, innerError: IErrorDetail): IErrorDetail;
/**
 * Adds AI suggestions to an error detail.
 *
 * @param error - The error detail to enhance.
 * @param suggestions - AI-generated suggestions.
 * @param auditId - Audit trail ID.
 * @returns New IErrorDetail with AI suggestions.
 */
declare function withAISuggestions(error: IErrorDetail, suggestions: IAISuggestions, auditId: string): IErrorDetail;
/**
 * Creates an aggregated error from multiple error details.
 *
 * @param errors - Array of errors to aggregate.
 * @param message - Optional custom message.
 * @param correlationId - Optional correlation ID.
 * @returns Aggregated IErrorDetail with all errors.
 */
declare function createAggregatedError(errors: IErrorDetail[], message?: string, correlationId?: string): IErrorDetail;

/**
 * @fileoverview Safe Execution Utilities
 * @module @ark.alliance/core/result/utilities/SafeExecute
 *
 * Utility functions for safely executing operations.
 * Wraps functions in try/catch and returns Result objects.
 *
 * @author Armand Richelet-Kleinberg ; with Anthropic Claude Opus 4.5 model
 */

/**
 * Options for safe execution.
 *
 * @interface ISafeExecuteOptions
 */
interface ISafeExecuteOptions {
    /** Correlation ID for tracing. */
    correlationId?: string;
    /** Custom error code for failures. */
    errorCode?: string;
    /** Error callback for logging or monitoring. */
    onError?: (error: Error, correlationId?: string) => void;
}
/**
 * Safely executes a synchronous function that returns a Result.
 *
 * @template T - The type of the success data.
 * @param fn - Function that returns a Result.
 * @param options - Execution options.
 * @returns Result from the function or error Result if exception occurred.
 */
declare function safeExecute<T>(fn: () => Result<T>, options?: ISafeExecuteOptions): Result<T>;
/**
 * Safely executes an asynchronous function that returns a Promise<Result>.
 *
 * @template T - The type of the success data.
 * @param fn - Async function that returns a Result.
 * @param options - Execution options.
 * @returns Promise of Result from the function or error Result if exception occurred.
 */
declare function safeExecuteAsync<T>(fn: () => Promise<Result<T>>, options?: ISafeExecuteOptions): Promise<Result<T>>;
/**
 * Safely executes a synchronous function that returns raw data.
 *
 * @template T - The type of the returned data.
 * @param fn - Function that returns data.
 * @param options - Execution options.
 * @returns Result containing the function's return value.
 */
declare function tryExecute<T>(fn: () => T, options?: ISafeExecuteOptions): Result<T>;
/**
 * Safely executes an asynchronous function that returns raw data.
 *
 * @template T - The type of the returned data.
 * @param fn - Async function that returns data.
 * @param options - Execution options.
 * @returns Promise of Result containing the function's return value.
 */
declare function tryExecuteAsync<T>(fn: () => Promise<T>, options?: ISafeExecuteOptions): Promise<Result<T>>;
/**
 * Logs a Result based on its status at the appropriate log level.
 *
 * @template T - The type of the result data.
 * @param result - The result to log.
 * @param logger - Logger implementation.
 * @param operationName - Name of the operation for context.
 */
declare function logResult<T>(result: Result<T>, logger: IResultLogger, operationName?: string): void;
/**
 * Safely executes an async function with logging integration.
 *
 * @template T - The type of the result data.
 * @param fn - Async function that returns a Result.
 * @param logger - Logger implementation.
 * @param operationName - Name of the operation for logging.
 * @param options - Execution options.
 * @returns Promise of Result from the function.
 */
declare function safeExecuteWithLog<T>(fn: () => Promise<Result<T>>, logger: IResultLogger, operationName: string, options?: ISafeExecuteOptions): Promise<Result<T>>;
/**
 * @deprecated Use ISafeExecuteOptions instead.
 */
type SafeExecuteOptions = ISafeExecuteOptions;

/**
 * @fileoverview Retry Helper Utility
 * @module @ark.alliance/core/result/utilities/RetryHelper
 *
 * Utility for retrying operations that return Result types.
 * Uses exponential backoff with jitter for retryable failures.
 *
 * @author Armand Richelet-Kleinberg ; with Anthropic Claude Opus 4.5 model
 */

/**
 * Executes an async operation with automatic retries for retryable failures.
 *
 * @template T - The type of the success data.
 * @param operation - The async function that returns a Result.
 * @param options - Optional retry configuration.
 * @returns Promise resolving to the Result (success or last failure).
 *
 * @remarks
 * Retries only occur for results where `isRetryableStatus()` returns true:
 * - TIMEOUT
 * - RATE_LIMITED
 * - SERVICE_UNAVAILABLE
 * - NO_CONNECTION
 * - CIRCUIT_OPEN
 * - BULKHEAD_REJECTED
 *
 * Uses exponential backoff: delay = baseDelayMs * (backoffMultiplier ^ attempt)
 * Adds jitter to prevent thundering herd.
 *
 * @example
 * ```typescript
 * const result = await retryWithResult(
 *     () => externalApiCall(),
 *     {
 *         maxAttempts: 5,
 *         baseDelayMs: 200,
 *         onRetry: (attempt, error, delay) => {
 *             console.log(`Attempt ${attempt} failed, retrying in ${delay}ms`);
 *         }
 *     }
 * );
 * ```
 */
declare function retryWithResult<T>(operation: () => Promise<Result<T>>, options?: IRetryOptions): Promise<Result<T>>;

export { type AISuggestions, type ApiResponse, BulkheadDefaults, CircuitBreakerDefaults, DefaultMessages, DefaultRetryOptions, type ErrorCode, ErrorCodes, type ErrorDetail, type ExceptionDto, type HttpStatusCode, HttpStatusCodes, type IAISuggestions, type IAggregatedError, type IApiResponse, type IErrorDetail, type IExceptionDto, type IPagedResultDto, type IPagedResultJSON, type IPaginationInfoDTO, type IResultDto, type IResultDtoBase, type IResultJSON, type IResultLogger, type IResultMetrics, type IRetryOptions, type ISafeExecuteOptions, type IVoidResultDto, type MetricsListener, PagedResult, type PagedResultDto, type PagedResultJSON, PaginationInfo, RateLimitDefaults, Result, type ResultDto, type ResultDtoBase, ResultException, type ResultJSON, type ResultLogger, type ResultMetrics, ResultStatus, type ResultStatusType, RetryDefaults, type SafeExecuteOptions, ServiceDefaults, type ServiceResult, TimingDefaults, type VoidResultDto, chainError, createAggregatedError, createApiResponse, createBulkheadRejectedError, createCircuitOpenError, createConflictError, createErrorDetail, createForbiddenError, createNotFoundError, createPagedApiResponse, createRateLimitedError, createTimeoutError, createUnauthorizedError, createValidationError, errorResult, fromPagedResultDto, getHttpStatusCode, isAggregatedError, isAlreadyStatus, isBulkheadRejectedStatus, isCancelledStatus, isCircuitOpenStatus, isForbiddenStatus, isNetworkErrorStatus, isNotFoundStatus, isNotImplementedStatus, isNotSuccessStatus, isPendingStatus, isRateLimitedStatus, isRetryableStatus, isSuccessStatus, isTerminalStatus, isTimeoutStatus, isUnauthorizedStatus, isUnexpectedStatus, isValidationErrorStatus, logResult, onResultMetrics, retryWithResult, safeExecute, safeExecuteAsync, safeExecuteWithLog, successResult, toExceptionDto, toHttpStatusCode, toPagedResultDto, toResultDto, tryExecute, tryExecuteAsync, withAISuggestions };
