/**
 * MCP Server Error Handling
 *
 * FAIL FAST: All errors throw immediately with descriptive context.
 * NO graceful degradation, NO fallbacks.
 *
 * @module server/errors
 */
/**
 * Error categories for MCP tool errors
 * Each category maps to specific failure modes for debugging
 */
export type ErrorCategory = 'VALIDATION_ERROR' | 'DATABASE_NOT_FOUND' | 'DATABASE_NOT_SELECTED' | 'DATABASE_ALREADY_EXISTS' | 'DOCUMENT_NOT_FOUND' | 'PROVENANCE_NOT_FOUND' | 'PROVENANCE_CHAIN_BROKEN' | 'INTEGRITY_VERIFICATION_FAILED' | 'OCR_TIMEOUT' | 'GPU_NOT_AVAILABLE' | 'EMBEDDING_FAILED' | 'VLM_API_ERROR' | 'IMAGE_EXTRACTION_FAILED' | 'CLUSTERING_ERROR' | 'GPU_OUT_OF_MEMORY' | 'EMBEDDING_MODEL_ERROR' | 'PATH_NOT_FOUND' | 'PATH_NOT_DIRECTORY' | 'PERMISSION_DENIED' | 'CONFIGURATION_ERROR' | 'INTERNAL_ERROR';
/**
 * MCPError - Structured error class for all MCP tool failures
 *
 * FAIL FAST: Thrown immediately when any error condition is detected.
 * Provides category, message, and optional details for debugging.
 */
export declare class MCPError extends Error {
    readonly category: ErrorCategory;
    readonly details?: Record<string, unknown>;
    constructor(category: ErrorCategory, message: string, details?: Record<string, unknown>);
    /**
     * Create error from unknown caught value
     * FAIL FAST: Always produces a typed error
     */
    static fromUnknown(error: unknown, defaultCategory?: ErrorCategory): MCPError;
    /**
     * Convert to JSON for logging/serialization
     */
    toJSON(): Record<string, unknown>;
}
/**
 * Recovery hint for AI agents to self-correct after errors.
 * Every ErrorCategory maps to a suggested tool and human-readable hint.
 */
export interface RecoveryHint {
    tool: string;
    hint: string;
}
/**
 * Get recovery hint for an error category.
 * Exported for testing and direct use.
 */
export declare function getRecoveryHint(category: ErrorCategory): RecoveryHint;
/**
 * Format MCPError for tool response
 * ALWAYS includes category, message, recovery hint, and optional details.
 * The recovery field tells AI agents which tool to call next and how to fix the issue.
 */
export declare function formatErrorResponse(error: MCPError): {
    success: false;
    error: {
        category: ErrorCategory;
        message: string;
        recovery: RecoveryHint;
        details?: Record<string, unknown>;
    };
};
/**
 * Create validation error
 */
export declare function validationError(message: string, details?: Record<string, unknown>): MCPError;
/**
 * Create database not selected error
 */
export declare function databaseNotSelectedError(): MCPError;
/**
 * Create database not found error
 */
export declare function databaseNotFoundError(name: string, storagePath?: string): MCPError;
/**
 * Create database already exists error
 */
export declare function databaseAlreadyExistsError(name: string): MCPError;
/**
 * Create document not found error
 */
export declare function documentNotFoundError(documentId: string): MCPError;
/**
 * Create provenance not found error
 */
export declare function provenanceNotFoundError(itemId: string): MCPError;
/**
 * Create path not found error
 */
export declare function pathNotFoundError(path: string): MCPError;
/**
 * Create path not directory error
 */
export declare function pathNotDirectoryError(path: string): MCPError;
//# sourceMappingURL=errors.d.ts.map