Add protocol for migration service

Sources/DataRaft/Protocols/DatabaseServiceProtocol.swift

@@ -3,51 +3,84 @@ import DataLiteCore
 
 /// A protocol that defines a common interface for working with a database connection.
 ///
-/// Conforming types provide methods for executing closures with a live `Connection`, optionally
-/// wrapped in transactions. These closures are guaranteed to execute in a thread-safe and
-/// serialized manner. Implementations may also support reconnecting and managing encryption keys.
+/// `DatabaseServiceProtocol` abstracts the core operations required to safely interact with a
+/// SQLite-compatible database. Conforming types provide thread-safe execution of closures with a live
+/// `Connection`, optional transaction support, reconnection logic, and pluggable encryption key
+/// management via a ``DatabaseServiceKeyProvider``.
+///
+/// This protocol forms the foundation for safe, modular service layers on top of a database.
+///
+/// ## Topics
+///
+/// ### Key Management
+///
+/// - ``DatabaseServiceKeyProvider``
+/// - ``keyProvider``
+///
+/// ### Connection Management
+///
+/// - ``reconnect()``
+///
+/// ### Database Operations
+///
+/// - ``Perform``
+/// - ``perform(_:)``
+/// - ``perform(in:closure:)``
 public protocol DatabaseServiceProtocol: AnyObject {
     /// A closure that performs a database operation using an active connection.
     ///
-    /// The `Perform<T>` alias defines the signature for a database operation block
-    /// that receives a live `Connection` and either returns a result or throws an error.
-    /// It is commonly used to express atomic units of work in ``perform(_:)`` or
-    /// ``perform(in:closure:)`` calls.
+    /// The `Perform<T>` type alias defines a closure signature for a database operation that
+    /// receives a live `Connection` and returns a value or throws an error. This enables
+    /// callers to express discrete, atomic database operations for execution via
+    /// ``perform(_:)`` or ``perform(in:closure:)``.
     ///
-    /// - Parameter T: The result type returned by the closure.
-    /// - Returns: A value of type `T` produced by the closure.
-    /// - Throws: Any error that occurs during execution of the database operation.
+    /// - Parameter connection: The active database connection.
+    /// - Returns: The result of the operation.
+    /// - Throws: Any error thrown during execution of the operation.
     typealias Perform<T> = (Connection) throws -> T
     
     /// The object responsible for providing encryption keys for the database connection.
     ///
-    /// When assigned, the key provider will be queried for a new key and applied to the current
-    /// connection, if available.
+    /// When assigned, the key provider will be queried for a key and applied to the current
+    /// connection, if available. If key retrieval or application fails, the error is reported
+    /// via `databaseService(_:didReceive:)` and not thrown from the setter.
+    ///
+    /// - Important: Setting this property does not guarantee that the connection becomes available;
+    ///   error handling is asynchronous via callback.
     var keyProvider: DatabaseServiceKeyProvider? { get set }
     
     /// Re-establishes the database connection using the stored provider.
     ///
-    /// If a `keyProvider` is set, the returned connection will attempt to apply a new key.
+    /// If a `keyProvider` is set, the method attempts to retrieve and apply a key
+    /// to the new connection. All errors encountered during connection creation or
+    /// key application are thrown. If an error occurs that is related to encryption key
+    /// retrieval or application, it is also reported to the `DatabaseServiceKeyProvider`
+    /// via its `databaseService(_:didReceive:)` callback.
     ///
     /// - Throws: Any error that occurs during connection creation or key application.
     func reconnect() throws
     
-    /// Executes the given closure with a live connection.
+    /// Executes the given closure with a live connection in a thread-safe manner.
     ///
-    /// - Parameter closure: The operation to execute.
+    /// All invocations are serialized to prevent concurrent database access.
+    ///
+    /// - Parameter closure: The database operation to perform.
     /// - Returns: The result produced by the closure.
-    /// - Throws: Any error thrown during execution.
+    /// - Throws: Any error thrown by the closure.
     func perform<T>(_ closure: Perform<T>) rethrows -> T
     
     /// Executes the given closure within a transaction.
     ///
-    /// If no transaction is active, a new one is started and committed or rolled back as needed.
+    /// If no transaction is active, a new transaction of the specified type is started. The closure
+    /// is executed atomically: if it succeeds, the transaction is committed; if it throws, the
+    /// transaction is rolled back. If a transaction is already active, the closure is executed
+    /// without starting a new one.
     ///
     /// - Parameters:
-    ///   - transaction: The transaction type to begin.
-    ///   - closure: The operation to execute within the transaction.
+    ///   - transaction: The type of transaction to begin (e.g., `deferred`, `immediate`, `exclusive`).
+    ///   - closure: The database operation to perform within the transaction.
     /// - Returns: The result produced by the closure.
-    /// - Throws: Any error thrown by the closure or transaction.
+    /// - Throws: Any error thrown by the closure or transaction control statements.
     func perform<T>(
         in transaction: TransactionType,
         closure: Perform<T>