Data Access Layer: Complete repository interface architecture

- Add IRepository<T,K> base interface with comprehensive kingdom-scoped operations
- Add IKingdomRepository with population management, KvK matchmaking, and democratic systems
- Add IPlayerRepository with castle progression, VIP systems, and teleportation mechanics
- Add IAllianceRepository with coalition systems, research trees, and territory management
- Add ICombatLogRepository with field interception, battle resolution, and combat analytics
- Add IPurchaseLogRepository with monetization tracking, chargeback protection, and anti-pay-to-win monitoring
- Add IUnitOfWork with transaction management, bulk operations, and cross-repository coordination

Key architectural features:
* Kingdom-scoped security preventing cross-kingdom data access
* Comprehensive async/await patterns for scalability
* Transaction-safe complex operations (KvK events, mergers, purchases)
* Anti-pay-to-win balance monitoring and skill-based alternatives
* Field interception system (core innovation) with battle mechanics
* Coalition system preserving alliance identity during kingdom events
* Secret tier VIP progression and chargeback protection
* Production-ready interfaces with detailed error handling specifications

All interfaces include comprehensive documentation, exception specifications,
and kingdom-scoped security patterns. Ready for concrete EF Core implementation.

ShadowedRealmsMobile/src/server/ShadowedRealms.Core/Interfaces/IUnitOfWork.cs

@@ -0,0 +1,388 @@
+/*
+ * File: /src/server/ShadowedRealms.Core/Interfaces/IUnitOfWork.cs
+ * Created: 2025-10-19
+ * Last Modified: 2025-10-19
+ * Description: Unit of Work interface providing centralized transaction management and repository coordination.
+ *              Ensures data consistency across complex operations involving multiple entities and repositories.
+ *              Critical for maintaining kingdom-scoped data integrity and handling complex business operations
+ *              like KvK events, alliance coalitions, and purchase processing that span multiple entities.
+ * Last Edit Notes: Initial implementation with comprehensive transaction management, repository coordination, and kingdom-scoped operations.
+ */
+
+using ShadowedRealms.Core.Interfaces.Repositories;
+using System.Data;
+
+namespace ShadowedRealms.Core.Interfaces
+{
+    /// <summary>
+    /// Unit of Work interface providing centralized transaction management and repository coordination
+    /// for complex operations spanning multiple entities. Ensures data consistency and kingdom-scoped
+    /// security across all database operations while supporting distributed transactions and rollback scenarios.
+    /// </summary>
+    public interface IUnitOfWork : IDisposable
+    {
+        #region Repository Access Properties
+
+        /// <summary>
+        /// Gets the Kingdom repository for kingdom lifecycle, population management, KvK events, 
+        /// and democratic political systems. Root repository for kingdom-scoped operations.
+        /// </summary>
+        IKingdomRepository Kingdoms { get; }
+
+        /// <summary>
+        /// Gets the Player repository for castle progression, troop management, resource systems,
+        /// VIP mechanics, research, equipment, and all core individual gameplay features.
+        /// </summary>
+        IPlayerRepository Players { get; }
+
+        /// <summary>
+        /// Gets the Alliance repository for social systems, coalition mechanics, research trees,
+        /// territory management, 5-tier hierarchy, and democratic leadership systems.
+        /// </summary>
+        IAllianceRepository Alliances { get; }
+
+        /// <summary>
+        /// Gets the Combat Log repository for field interception system, battle resolution,
+        /// KvK events, stealth mechanics, dragon integration, and combat analytics.
+        /// </summary>
+        ICombatLogRepository CombatLogs { get; }
+
+        /// <summary>
+        /// Gets the Purchase Log repository for monetization tracking, chargeback protection,
+        /// VIP progression, revenue analytics, and anti-pay-to-win balance monitoring.
+        /// </summary>
+        IPurchaseLogRepository PurchaseLogs { get; }
+
+        #endregion
+
+        #region Transaction Management
+
+        /// <summary>
+        /// Begins a new database transaction with the specified isolation level for complex operations
+        /// requiring data consistency across multiple repositories. Automatically applies kingdom-scoped security.
+        /// </summary>
+        /// <param name="isolationLevel">The isolation level for the transaction</param>
+        /// <param name="kingdomId">The kingdom context for the transaction (for security scoping)</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Task representing the transaction initiation</returns>
+        /// <exception cref="ArgumentException">Thrown when kingdomId is invalid</exception>
+        /// <exception cref="InvalidOperationException">Thrown when transaction cannot be started</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task BeginTransactionAsync(IsolationLevel isolationLevel = IsolationLevel.ReadCommitted, int? kingdomId = null,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Commits the current transaction, persisting all changes made within the transaction scope.
+        /// Validates kingdom-scoped security before commit and ensures data consistency across all repositories.
+        /// </summary>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Task representing the commit operation</returns>
+        /// <exception cref="InvalidOperationException">Thrown when no active transaction or commit fails</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task CommitTransactionAsync(CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Rolls back the current transaction, discarding all changes made within the transaction scope.
+        /// Automatically triggered on exceptions or explicit rollback requests to maintain data integrity.
+        /// </summary>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Task representing the rollback operation</returns>
+        /// <exception cref="InvalidOperationException">Thrown when no active transaction or rollback fails</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task RollbackTransactionAsync(CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Executes an operation within a transaction scope, automatically handling commit/rollback.
+        /// Provides transaction safety for complex business operations spanning multiple repositories.
+        /// </summary>
+        /// <typeparam name="TResult">The return type of the operation</typeparam>
+        /// <param name="operation">The operation to execute within the transaction</param>
+        /// <param name="isolationLevel">The isolation level for the transaction</param>
+        /// <param name="kingdomId">The kingdom context for transaction security</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>The result of the operation if successful</returns>
+        /// <exception cref="ArgumentNullException">Thrown when operation is null</exception>
+        /// <exception cref="ArgumentException">Thrown when kingdomId is invalid</exception>
+        /// <exception cref="InvalidOperationException">Thrown when transaction execution fails</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<TResult> ExecuteInTransactionAsync<TResult>(Func<IUnitOfWork, Task<TResult>> operation,
+            IsolationLevel isolationLevel = IsolationLevel.ReadCommitted, int? kingdomId = null,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Executes an operation within a transaction scope without return value, automatically handling commit/rollback.
+        /// Provides transaction safety for complex business operations that don't return data.
+        /// </summary>
+        /// <param name="operation">The operation to execute within the transaction</param>
+        /// <param name="isolationLevel">The isolation level for the transaction</param>
+        /// <param name="kingdomId">The kingdom context for transaction security</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Task representing the operation completion</returns>
+        /// <exception cref="ArgumentNullException">Thrown when operation is null</exception>
+        /// <exception cref="ArgumentException">Thrown when kingdomId is invalid</exception>
+        /// <exception cref="InvalidOperationException">Thrown when transaction execution fails</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task ExecuteInTransactionAsync(Func<IUnitOfWork, Task> operation,
+            IsolationLevel isolationLevel = IsolationLevel.ReadCommitted, int? kingdomId = null,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Gets the current transaction status including isolation level, kingdom context, and duration.
+        /// Used for debugging, monitoring, and ensuring proper transaction management.
+        /// </summary>
+        /// <returns>Current transaction status information</returns>
+        (bool HasActiveTransaction, IsolationLevel? IsolationLevel, int? KingdomId, TimeSpan? Duration) GetTransactionStatus();
+
+        #endregion
+
+        #region Change Tracking and Persistence
+
+        /// <summary>
+        /// Saves all pending changes across all repositories to the database without using transactions.
+        /// Applies kingdom-scoped validation and maintains referential integrity across all entity changes.
+        /// </summary>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>The number of entities successfully saved</returns>
+        /// <exception cref="InvalidOperationException">Thrown when save operation fails due to validation or conflicts</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<int> SaveChangesAsync(CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Gets the count of pending changes across all repositories for monitoring and validation.
+        /// Helps identify complex operations and potential performance impacts before committing.
+        /// </summary>
+        /// <returns>Count of pending changes by entity type and operation</returns>
+        Dictionary<string, (int Added, int Modified, int Deleted)> GetPendingChanges();
+
+        /// <summary>
+        /// Discards all pending changes across all repositories, reverting to the last saved state.
+        /// Used for cancellation scenarios and error recovery without database rollback.
+        /// </summary>
+        void DiscardChanges();
+
+        /// <summary>
+        /// Validates all pending changes against business rules and kingdom-scoped security before persistence.
+        /// Provides early validation to prevent transaction failures and ensure data integrity.
+        /// </summary>
+        /// <param name="kingdomId">The kingdom context for validation</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Validation results with details of any rule violations</returns>
+        /// <exception cref="ArgumentException">Thrown when kingdomId is invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<(bool IsValid, Dictionary<string, string[]> ValidationErrors)> ValidatePendingChangesAsync(int kingdomId,
+            CancellationToken cancellationToken = default);
+
+        #endregion
+
+        #region Complex Business Operations
+
+        /// <summary>
+        /// Executes a complete KvK event initialization spanning kingdoms, alliances, combat logs, and coalition setup.
+        /// Demonstrates complex multi-repository transaction coordination with rollback safety.
+        /// </summary>
+        /// <param name="kvkConfiguration">Complete KvK event configuration</param>
+        /// <param name="participatingKingdoms">Kingdoms participating in the event</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Created KvK event with all supporting data structures</returns>
+        /// <exception cref="ArgumentException">Thrown when configuration is invalid or kingdoms ineligible</exception>
+        /// <exception cref="InvalidOperationException">Thrown when KvK initialization fails</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<object> InitializeKvKEventAsync(object kvkConfiguration, IEnumerable<int> participatingKingdoms,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Processes a complete purchase transaction including player updates, VIP progression, purchase logging,
+        /// and fraud detection across multiple repositories with full transaction safety.
+        /// </summary>
+        /// <param name="purchaseRequest">Complete purchase request information</param>
+        /// <param name="playerId">The player making the purchase</param>
+        /// <param name="kingdomId">The kingdom context for the purchase</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Complete purchase result with all updates applied</returns>
+        /// <exception cref="ArgumentException">Thrown when purchase request is invalid</exception>
+        /// <exception cref="InvalidOperationException">Thrown when purchase processing fails</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<object> ProcessCompletePurchaseAsync(object purchaseRequest, int playerId, int kingdomId,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Executes alliance merger including member transfers, research preservation, territory reassignment,
+        /// and historical data consolidation across multiple entities with transaction safety.
+        /// </summary>
+        /// <param name="survivingAllianceId">The alliance that will continue to exist</param>
+        /// <param name="mergingAllianceId">The alliance being absorbed</param>
+        /// <param name="mergerConfiguration">Merger rules and member handling</param>
+        /// <param name="kingdomId">The kingdom context for the merger</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Merger result with updated alliance and member status</returns>
+        /// <exception cref="ArgumentException">Thrown when merger parameters are invalid</exception>
+        /// <exception cref="InvalidOperationException">Thrown when merger execution fails</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<object> ExecuteAllianceMergerAsync(int survivingAllianceId, int mergingAllianceId,
+            object mergerConfiguration, int kingdomId, CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Processes kingdom merger including population transfers, alliance reassignments, combat history consolidation,
+        /// and democratic system integration across all entity types with comprehensive transaction management.
+        /// </summary>
+        /// <param name="survivingKingdomId">The kingdom that will continue to exist</param>
+        /// <param name="mergingKingdomId">The kingdom being absorbed</param>
+        /// <param name="mergerConfiguration">Kingdom merger rules and integration settings</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Comprehensive merger result with updated kingdom and all associated entities</returns>
+        /// <exception cref="ArgumentException">Thrown when merger parameters are invalid or kingdoms incompatible</exception>
+        /// <exception cref="InvalidOperationException">Thrown when kingdom merger execution fails</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<object> ProcessKingdomMergerAsync(int survivingKingdomId, int mergingKingdomId,
+            object mergerConfiguration, CancellationToken cancellationToken = default);
+
+        #endregion
+
+        #region Performance and Monitoring
+
+        /// <summary>
+        /// Gets comprehensive performance metrics for all repositories including query performance,
+        /// transaction duration, change tracking efficiency, and kingdom-scoped operation statistics.
+        /// </summary>
+        /// <param name="metricsTimeframe">Time period for performance metrics collection</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Detailed performance metrics with optimization recommendations</returns>
+        /// <exception cref="ArgumentException">Thrown when timeframe is invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<object> GetPerformanceMetricsAsync(TimeSpan metricsTimeframe, CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Validates data consistency across all repositories and entities, identifying referential integrity
+        /// issues, orphaned records, and kingdom-scoped data leaks for maintenance and debugging.
+        /// </summary>
+        /// <param name="kingdomId">The kingdom to validate (null for global validation)</param>
+        /// <param name="validationScope">Scope of validation (quick, standard, comprehensive)</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Data consistency validation results with identified issues and repair recommendations</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<object> ValidateDataConsistencyAsync(int? kingdomId = null, string validationScope = "standard",
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Optimizes database performance by analyzing query patterns, updating statistics, reorganizing indexes,
+        /// and cleaning up fragmented data across all entity tables for improved operation efficiency.
+        /// </summary>
+        /// <param name="optimizationType">Type of optimization (indexes, statistics, cleanup, full)</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Optimization results with performance improvements and recommendations</returns>
+        /// <exception cref="ArgumentException">Thrown when optimization type is invalid</exception>
+        /// <exception cref="InvalidOperationException">Thrown when optimization fails</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<object> OptimizeDatabasePerformanceAsync(string optimizationType = "standard",
+            CancellationToken cancellationToken = default);
+
+        #endregion
+
+        #region Bulk Operations and Data Migration
+
+        /// <summary>
+        /// Executes bulk operations across multiple repositories with transaction safety and progress tracking.
+        /// Optimized for large-scale data operations like server mergers, mass updates, and data migrations.
+        /// </summary>
+        /// <typeparam name="TResult">The return type of the bulk operation</typeparam>
+        /// <param name="bulkOperation">The bulk operation to execute</param>
+        /// <param name="batchSize">Size of batches for processing (for memory management)</param>
+        /// <param name="kingdomId">The kingdom context for bulk operations</param>
+        /// <param name="progressCallback">Callback for progress reporting</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Bulk operation result with processing statistics</returns>
+        /// <exception cref="ArgumentNullException">Thrown when bulk operation is null</exception>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="InvalidOperationException">Thrown when bulk operation fails</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<TResult> ExecuteBulkOperationAsync<TResult>(Func<IUnitOfWork, int, Task<TResult>> bulkOperation,
+            int batchSize = 1000, int? kingdomId = null, IProgress<(int Processed, int Total, string Status)>? progressCallback = null,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Migrates data between kingdoms during server consolidation or kingdom mergers with full referential
+        /// integrity maintenance and audit trail creation for complex data transformation scenarios.
+        /// </summary>
+        /// <param name="sourceKingdomId">The kingdom data is being migrated from</param>
+        /// <param name="targetKingdomId">The kingdom data is being migrated to</param>
+        /// <param name="migrationConfiguration">Migration rules, mappings, and transformation logic</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Migration result with transferred data statistics and audit information</returns>
+        /// <exception cref="ArgumentException">Thrown when kingdom IDs are invalid or migration config is malformed</exception>
+        /// <exception cref="InvalidOperationException">Thrown when data migration fails</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<object> MigrateKingdomDataAsync(int sourceKingdomId, int targetKingdomId, object migrationConfiguration,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Creates comprehensive database backup including all kingdom data, transaction logs, and metadata
+        /// with optional encryption for disaster recovery and data protection purposes.
+        /// </summary>
+        /// <param name="backupConfiguration">Backup settings including compression, encryption, and scope</param>
+        /// <param name="kingdomIds">Specific kingdoms to backup (null for all kingdoms)</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Backup result with file information, verification checksums, and restoration instructions</returns>
+        /// <exception cref="ArgumentException">Thrown when backup configuration is invalid</exception>
+        /// <exception cref="InvalidOperationException">Thrown when backup creation fails</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<object> CreateDatabaseBackupAsync(object backupConfiguration, IEnumerable<int>? kingdomIds = null,
+            CancellationToken cancellationToken = default);
+
+        #endregion
+
+        #region Kingdom-Scoped Security and Validation
+
+        /// <summary>
+        /// Validates that all operations within the unit of work respect kingdom boundaries and security constraints.
+        /// Prevents accidental cross-kingdom data access and ensures proper security isolation.
+        /// </summary>
+        /// <param name="kingdomId">The kingdom context to validate against</param>
+        /// <param name="operationType">The type of operation being validated</param>
+        /// <returns>Security validation result with any violations identified</returns>
+        /// <exception cref="ArgumentException">Thrown when kingdomId is invalid</exception>
+        /// <exception cref="UnauthorizedAccessException">Thrown when security violations are detected</exception>
+        (bool IsSecure, string[] SecurityViolations, string[] Recommendations) ValidateKingdomScopedSecurity(
+            int kingdomId, string operationType);
+
+        /// <summary>
+        /// Enforces kingdom-scoped query filters across all repositories to prevent accidental data leakage
+        /// between kingdoms. Automatically applied to all queries within the unit of work context.
+        /// </summary>
+        /// <param name="kingdomId">The kingdom context for query filtering</param>
+        /// <exception cref="ArgumentException">Thrown when kingdomId is invalid</exception>
+        /// <exception cref="InvalidOperationException">Thrown when filter enforcement fails</exception>
+        void EnforceKingdomQueryFilters(int kingdomId);
+
+        /// <summary>
+        /// Temporarily elevates permissions for cross-kingdom operations requiring administrative access.
+        /// Used for system maintenance, data migration, and administrative reporting with full audit logging.
+        /// </summary>
+        /// <param name="adminId">The administrator requesting elevated permissions</param>
+        /// <param name="elevationReason">Business justification for permission elevation</param>
+        /// <param name="operationScope">Scope of operations requiring elevation</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Elevation token for authorized cross-kingdom operations</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="UnauthorizedAccessException">Thrown when admin lacks elevation authority</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<object> ElevatePermissionsAsync(int adminId, string elevationReason, string operationScope,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Revokes elevated permissions and logs the completion of cross-kingdom operations for audit trails.
+        /// Automatically called when elevation token expires or operations complete.
+        /// </summary>
+        /// <param name="elevationToken">The elevation token to revoke</param>
+        /// <param name="operationSummary">Summary of operations performed with elevated permissions</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Revocation result with audit log information</returns>
+        /// <exception cref="ArgumentException">Thrown when elevation token is invalid</exception>
+        /// <exception cref="InvalidOperationException">Thrown when permission revocation fails</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<object> RevokeElevatedPermissionsAsync(object elevationToken, string operationSummary,
+            CancellationToken cancellationToken = default);
+
+        #endregion
+    }
+}

ShadowedRealmsMobile/src/server/ShadowedRealms.Core/Interfaces/Repositories/IAllianceRepository.cs

@@ -0,0 +1,592 @@
+/*
+ * File: /src/server/ShadowedRealms.Core/Interfaces/Repositories/IAllianceRepository.cs
+ * Created: 2025-10-19
+ * Last Modified: 2025-10-19
+ * Description: Alliance repository interface defining alliance-specific data access operations.
+ *              Handles alliance lifecycle, coalition systems, research trees, territory management,
+ *              5-tier hierarchy, member management, and democratic leadership systems. Core innovation
+ *              is the coalition system that preserves alliance identity during KvK events.
+ * Last Edit Notes: Initial implementation with coalition mechanics, research trees, territory systems, and democratic leadership.
+ */
+
+using ShadowedRealms.Core.Models;
+using ShadowedRealms.Core.Models.Alliance;
+using System.Linq.Expressions;
+
+namespace ShadowedRealms.Core.Interfaces.Repositories
+{
+    /// <summary>
+    /// Repository interface for Alliance entity operations, providing comprehensive alliance lifecycle management,
+    /// coalition systems, research trees, territory control, democratic leadership, and member coordination.
+    /// Core innovation: Coalition system preserves alliance independence during kingdom events.
+    /// </summary>
+    public interface IAllianceRepository : IRepository<Alliance, int>
+    {
+        #region Alliance Lifecycle Management
+
+        /// <summary>
+        /// Creates a new alliance within the specified kingdom with initial configuration and founder assignment.
+        /// Automatically sets up 5-tier leadership hierarchy, research trees, and territory management systems.
+        /// </summary>
+        /// <param name="allianceName">The name for the new alliance (must be unique within kingdom)</param>
+        /// <param name="allianceTag">Short alliance tag (2-5 characters, unique within kingdom)</param>
+        /// <param name="founderId">The player who will become the alliance leader</param>
+        /// <param name="kingdomId">The kingdom where the alliance will be created</param>
+        /// <param name="foundingConfiguration">Initial alliance setup and policies</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>The newly created alliance with founder assigned as leader</returns>
+        /// <exception cref="ArgumentException">Thrown when name/tag is invalid, taken, or founder is ineligible</exception>
+        /// <exception cref="InvalidOperationException">Thrown when alliance creation fails due to system constraints</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<Alliance> CreateNewAllianceAsync(string allianceName, string allianceTag, int founderId, int kingdomId,
+            object foundingConfiguration, CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Gets an alliance by its unique tag within the specified kingdom context.
+        /// Used for alliance lookup, invitation systems, and diplomatic communications.
+        /// </summary>
+        /// <param name="allianceTag">The alliance tag to search for</param>
+        /// <param name="kingdomId">The kingdom context for the search</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>The alliance if found within the kingdom, null otherwise</returns>
+        /// <exception cref="ArgumentException">Thrown when allianceTag is null/empty or kingdomId is invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<Alliance?> GetAllianceByTagAsync(string allianceTag, int kingdomId,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Disbands an alliance, handling member redistribution, resource transfers, and historical data preservation.
+        /// Manages coalition withdrawals, territory releases, and research tree preservation for members.
+        /// </summary>
+        /// <param name="allianceId">The alliance to disband</param>
+        /// <param name="kingdomId">The kingdom context for the operation</param>
+        /// <param name="disbandReason">Reason for disbanding (for historical records)</param>
+        /// <param name="authorizingPlayerId">The leader authorizing the disbandment</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>True if alliance was successfully disbanded</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid or player lacks authority</exception>
+        /// <exception cref="InvalidOperationException">Thrown when alliance cannot be disbanded due to active commitments</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<bool> DisbandAllianceAsync(int allianceId, int kingdomId, string disbandReason, int authorizingPlayerId,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Archives an inactive alliance while preserving historical data and member contribution records.
+        /// Used for alliances that no longer have active leadership or sufficient membership.
+        /// </summary>
+        /// <param name="allianceId">The alliance to archive</param>
+        /// <param name="kingdomId">The kingdom context for the operation</param>
+        /// <param name="archiveReason">Reason for archiving (inactivity, merger, etc.)</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>True if alliance was archived successfully</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="InvalidOperationException">Thrown when alliance has active members or commitments</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<bool> ArchiveAllianceAsync(int allianceId, int kingdomId, string archiveReason,
+            CancellationToken cancellationToken = default);
+
+        #endregion
+
+        #region Coalition System (Core Innovation)
+
+        /// <summary>
+        /// Creates a coalition between multiple alliances for KvK events while preserving individual alliance identities.
+        /// CORE INNOVATION: Allows cross-alliance cooperation without forced merging or identity loss.
+        /// </summary>
+        /// <param name="participatingAllianceIds">Alliances joining the coalition</param>
+        /// <param name="coalitionName">Name for the temporary coalition</param>
+        /// <param name="eventType">Type of event requiring coalition (KvK, territory war, etc.)</param>
+        /// <param name="kingdomId">The kingdom context for the operation</param>
+        /// <param name="coalitionConfiguration">Coalition leadership structure and resource sharing rules</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>The created coalition with participating alliances</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid or alliances are ineligible</exception>
+        /// <exception cref="InvalidOperationException">Thrown when coalition creation fails due to conflicts</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<object> CreateCoalitionAsync(IEnumerable<int> participatingAllianceIds, string coalitionName,
+            string eventType, int kingdomId, object coalitionConfiguration, CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Gets alliances that are eligible for coalition participation based on compatibility metrics,
+        /// leadership activity, member engagement, and strategic alignment assessment.
+        /// </summary>
+        /// <param name="initiatingAllianceId">The alliance seeking coalition partners</param>
+        /// <param name="eventType">The type of event requiring coalition</param>
+        /// <param name="kingdomId">The kingdom context for the search</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Compatible alliances with compatibility scores and synergy analysis</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<IEnumerable<(Alliance Alliance, double CompatibilityScore, string[] SynergyAreas)>> GetCoalitionEligibleAlliancesAsync(
+            int initiatingAllianceId, string eventType, int kingdomId, CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Updates coalition participation status for an alliance, handling role assignments, resource contributions,
+        /// and coordination responsibilities while maintaining alliance independence.
+        /// </summary>
+        /// <param name="allianceId">The alliance updating coalition status</param>
+        /// <param name="coalitionId">The coalition being joined or left (null to leave all coalitions)</param>
+        /// <param name="participationRole">Role within the coalition (coordinator, support, specialist, etc.)</param>
+        /// <param name="kingdomId">The kingdom context for the operation</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Updated alliance with new coalition status</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid or role assignment fails</exception>
+        /// <exception cref="InvalidOperationException">Thrown when coalition change violates agreements</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<Alliance> UpdateCoalitionParticipationAsync(int allianceId, int? coalitionId, string? participationRole,
+            int kingdomId, CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Gets coalition performance metrics for participating alliances including contribution levels,
+        /// coordination effectiveness, and individual alliance achievements within coalition context.
+        /// </summary>
+        /// <param name="coalitionId">The coalition to analyze</param>
+        /// <param name="kingdomId">The kingdom context for the operation</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Coalition performance breakdown by participating alliance</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<object> GetCoalitionPerformanceMetricsAsync(int coalitionId, int kingdomId,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Dissolves a coalition while preserving individual alliance achievements and returning control
+        /// to individual alliance leadership. Handles resource redistribution and historical record keeping.
+        /// </summary>
+        /// <param name="coalitionId">The coalition to dissolve</param>
+        /// <param name="kingdomId">The kingdom context for the operation</param>
+        /// <param name="dissolutionReason">Reason for coalition dissolution</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Updated participating alliances with individual control restored</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="InvalidOperationException">Thrown when coalition cannot be dissolved due to active commitments</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<IEnumerable<Alliance>> DissolveCoalitionAsync(int coalitionId, int kingdomId, string dissolutionReason,
+            CancellationToken cancellationToken = default);
+
+        #endregion
+
+        #region Research Tree System
+
+        /// <summary>
+        /// Updates alliance research progress in specific technology areas, validating prerequisites,
+        /// resource costs, and member contribution requirements. Handles Military, Economic, and Technology branches.
+        /// </summary>
+        /// <param name="allianceId">The alliance conducting research</param>
+        /// <param name="researchArea">The research area being advanced (Military, Economic, Technology)</param>
+        /// <param name="researchLevel">The target research level</param>
+        /// <param name="contributingMembers">Members contributing resources to the research</param>
+        /// <param name="kingdomId">The kingdom context for the operation</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Updated alliance with new research level and unlocked bonuses</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid or research violates prerequisites</exception>
+        /// <exception cref="InvalidOperationException">Thrown when alliance lacks resources or member contributions</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<Alliance> UpdateAllianceResearchAsync(int allianceId, string researchArea, int researchLevel,
+            Dictionary<int, object> contributingMembers, int kingdomId, CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Gets alliances by research specialization for coalition formation, diplomatic relations,
+        /// and strategic partnership identification. Matches alliances with complementary research focuses.
+        /// </summary>
+        /// <param name="kingdomId">The kingdom to search within</param>
+        /// <param name="researchCriteria">Minimum research levels in specific areas</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Alliances meeting the research specialization criteria</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<IEnumerable<Alliance>> GetAlliancesByResearchSpecializationAsync(int kingdomId,
+            Dictionary<string, int> researchCriteria, CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Calculates total research bonuses available to alliance members including base alliance research,
+        /// coalition bonuses, and member contribution rewards. Used for individual player bonus calculations.
+        /// </summary>
+        /// <param name="allianceId">The alliance to calculate bonuses for</param>
+        /// <param name="kingdomId">The kingdom context for the operation</param>
+        /// <param name="includeCoalitionBonuses">Whether to include bonuses from coalition participation</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Comprehensive breakdown of all research bonuses available to members</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<object> CalculateAllianceResearchBonusesAsync(int allianceId, int kingdomId, bool includeCoalitionBonuses = true,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Records member contributions to alliance research including resources, time, and expertise.
+        /// Tracks individual contribution metrics for reward distribution and leadership evaluation.
+        /// </summary>
+        /// <param name="allianceId">The alliance receiving contributions</param>
+        /// <param name="memberId">The member making the contribution</param>
+        /// <param name="contributionDetails">Resources, time, or expertise contributed</param>
+        /// <param name="kingdomId">The kingdom context for the operation</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Updated alliance with recorded contribution and member recognition</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid or member is not in alliance</exception>
+        /// <exception cref="InvalidOperationException">Thrown when contribution cannot be processed</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<Alliance> RecordResearchContributionAsync(int allianceId, int memberId, object contributionDetails,
+            int kingdomId, CancellationToken cancellationToken = default);
+
+        #endregion
+
+        #region Territory Management
+
+        /// <summary>
+        /// Claims territory for an alliance, validating adjacency requirements, resource costs, and capacity limits.
+        /// Handles contested zones, proximity to other alliances, and strategic resource locations.
+        /// </summary>
+        /// <param name="allianceId">The alliance claiming territory</param>
+        /// <param name="territoryCoordinates">The coordinates of the territory to claim</param>
+        /// <param name="territoryType">Type of territory (standard, resource, strategic)</param>
+        /// <param name="kingdomId">The kingdom context for the operation</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Updated alliance with new territory claim</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid or territory cannot be claimed</exception>
+        /// <exception cref="InvalidOperationException">Thrown when alliance lacks requirements for territory claim</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<Alliance> ClaimTerritoryAsync(int allianceId, (int X, int Y) territoryCoordinates, string territoryType,
+            int kingdomId, CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Upgrades alliance territory buildings including resource generation facilities, defensive structures,
+        /// and member benefit buildings. Validates construction prerequisites and resource costs.
+        /// </summary>
+        /// <param name="allianceId">The alliance upgrading territory</param>
+        /// <param name="territoryId">The specific territory being upgraded</param>
+        /// <param name="buildingUpgrades">Dictionary of building types and target levels</param>
+        /// <param name="kingdomId">The kingdom context for the operation</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Updated alliance with upgraded territory buildings</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid or upgrades violate rules</exception>
+        /// <exception cref="InvalidOperationException">Thrown when alliance lacks resources for upgrades</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<Alliance> UpgradeTerritoryBuildingsAsync(int allianceId, int territoryId, Dictionary<string, int> buildingUpgrades,
+            int kingdomId, CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Gets alliances with territory in contested zones around strategic forest areas and resource locations.
+        /// Used for KvK planning, territorial conflicts, and strategic resource competition analysis.
+        /// </summary>
+        /// <param name="contestedZoneCoordinates">The contested zone to analyze</param>
+        /// <param name="kingdomId">The kingdom context for the search</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Alliances with territorial claims in the contested zone</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<IEnumerable<(Alliance Alliance, object TerritoryDetails)>> GetAlliancesInContestedZoneAsync(
+            (int X, int Y) contestedZoneCoordinates, int kingdomId, CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Calculates territory control bonuses for alliance members including resource generation,
+        /// defensive advantages, and strategic positioning benefits.
+        /// </summary>
+        /// <param name="allianceId">The alliance to calculate bonuses for</param>
+        /// <param name="kingdomId">The kingdom context for the operation</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Comprehensive territory bonus breakdown for alliance members</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<object> CalculateTerritoryBonusesAsync(int allianceId, int kingdomId,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Releases alliance territory claims, handling resource redistribution and member notification.
+        /// Can be voluntary (strategic repositioning) or forced (insufficient maintenance/defense).
+        /// </summary>
+        /// <param name="allianceId">The alliance releasing territory</param>
+        /// <param name="territoryIds">Specific territories to release (empty for all territory)</param>
+        /// <param name="releaseReason">Reason for territory release</param>
+        /// <param name="kingdomId">The kingdom context for the operation</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Updated alliance with released territories</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="InvalidOperationException">Thrown when territory release fails due to active conflicts</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<Alliance> ReleaseTerritoryAsync(int allianceId, IEnumerable<int>? territoryIds, string releaseReason,
+            int kingdomId, CancellationToken cancellationToken = default);
+
+        #endregion
+
+        #region 5-Tier Leadership Hierarchy
+
+        /// <summary>
+        /// Updates alliance leadership structure using the 5-tier hierarchy system with role-based permissions.
+        /// Handles Leader, Co-Leaders, Generals, Captains, and Members with appropriate authority delegation.
+        /// </summary>
+        /// <param name="allianceId">The alliance updating leadership</param>
+        /// <param name="leadershipChanges">Dictionary of member IDs and new roles</param>
+        /// <param name="authorizingPlayerId">The current leader authorizing changes</param>
+        /// <param name="kingdomId">The kingdom context for the operation</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Updated alliance with new leadership structure</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid or player lacks authority</exception>
+        /// <exception cref="InvalidOperationException">Thrown when leadership changes violate hierarchy rules</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<Alliance> UpdateLeadershipHierarchyAsync(int allianceId, Dictionary<int, string> leadershipChanges,
+            int authorizingPlayerId, int kingdomId, CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Gets alliance leadership structure with role assignments, permissions, and activity status.
+        /// Provides complete hierarchy visualization for member management and authority tracking.
+        /// </summary>
+        /// <param name="allianceId">The alliance to get leadership for</param>
+        /// <param name="kingdomId">The kingdom context for the operation</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Complete leadership hierarchy with roles and permissions</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<object> GetAllianceLeadershipAsync(int allianceId, int kingdomId,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Validates leadership action permissions based on role hierarchy and specific operation requirements.
+        /// Prevents unauthorized actions while supporting delegated authority within the alliance structure.
+        /// </summary>
+        /// <param name="allianceId">The alliance context for validation</param>
+        /// <param name="playerId">The player attempting the action</param>
+        /// <param name="actionType">The type of action being attempted</param>
+        /// <param name="kingdomId">The kingdom context for validation</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Permission validation result with authority level and restrictions</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<(bool IsAuthorized, string AuthorityLevel, string[] Restrictions)> ValidateLeadershipActionAsync(
+            int allianceId, int playerId, string actionType, int kingdomId, CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Initiates democratic leadership transition within the alliance, setting up voting systems
+        /// and succession planning for leadership changes and emergency leadership transfer.
+        /// </summary>
+        /// <param name="allianceId">The alliance conducting leadership transition</param>
+        /// <param name="transitionType">Type of transition (election, succession, emergency)</param>
+        /// <param name="candidateIds">Eligible candidates for leadership positions</param>
+        /// <param name="kingdomId">The kingdom context for the operation</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Leadership transition configuration with voting setup</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid or candidates are ineligible</exception>
+        /// <exception cref="InvalidOperationException">Thrown when transition cannot be initiated</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<object> InitiateLeadershipTransitionAsync(int allianceId, string transitionType, IEnumerable<int> candidateIds,
+            int kingdomId, CancellationToken cancellationToken = default);
+
+        #endregion
+
+        #region Member Management
+
+        /// <summary>
+        /// Processes member applications to join the alliance, validating eligibility requirements,
+        /// cooldown periods, and alliance capacity limits. Handles both applications and invitations.
+        /// </summary>
+        /// <param name="allianceId">The alliance receiving the application</param>
+        /// <param name="applicantId">The player applying to join</param>
+        /// <param name="applicationMethod">Application or invitation</param>
+        /// <param name="kingdomId">The kingdom context for the operation</param>
+        /// <param name="sponsoringMemberId">Member sponsoring the application (if applicable)</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Application result with status and next steps</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid or applicant is ineligible</exception>
+        /// <exception cref="InvalidOperationException">Thrown when application cannot be processed</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<object> ProcessMemberApplicationAsync(int allianceId, int applicantId, string applicationMethod,
+            int kingdomId, int? sponsoringMemberId = null, CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Removes a member from the alliance, handling voluntary departures, kicks, and disciplinary actions.
+        /// Manages resource contribution settlements, role transitions, and exit procedures.
+        /// </summary>
+        /// <param name="allianceId">The alliance losing the member</param>
+        /// <param name="memberId">The member being removed</param>
+        /// <param name="removalType">Voluntary departure, kick, or disciplinary action</param>
+        /// <param name="authorizingPlayerId">The leader authorizing the removal (for kicks)</param>
+        /// <param name="kingdomId">The kingdom context for the operation</param>
+        /// <param name="removalReason">Reason for removal (for record keeping)</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Updated alliance with member removed and resources settled</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid or player lacks authority</exception>
+        /// <exception cref="InvalidOperationException">Thrown when member removal violates alliance policies</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<Alliance> RemoveMemberAsync(int allianceId, int memberId, string removalType, int kingdomId,
+            int? authorizingPlayerId = null, string? removalReason = null, CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Updates member contribution tracking including research donations, territory support,
+        /// military assistance, and social engagement metrics for recognition and reward systems.
+        /// </summary>
+        /// <param name="allianceId">The alliance tracking contributions</param>
+        /// <param name="memberId">The member making contributions</param>
+        /// <param name="contributionData">Detailed contribution information</param>
+        /// <param name="kingdomId">The kingdom context for the operation</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Updated alliance with recorded member contributions</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid or member is not in alliance</exception>
+        /// <exception cref="InvalidOperationException">Thrown when contribution tracking fails</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<Alliance> UpdateMemberContributionsAsync(int allianceId, int memberId, object contributionData,
+            int kingdomId, CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Gets member performance analytics for alliance management including activity levels,
+        /// contribution history, leadership potential, and social engagement metrics.
+        /// </summary>
+        /// <param name="allianceId">The alliance to analyze members for</param>
+        /// <param name="analysisType">Type of analysis (performance, potential, engagement)</param>
+        /// <param name="kingdomId">The kingdom context for the operation</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Member analytics with performance rankings and development recommendations</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<object> GetMemberPerformanceAnalyticsAsync(int allianceId, string analysisType, int kingdomId,
+            CancellationToken cancellationToken = default);
+
+        #endregion
+
+        #region Resource and Economic Management
+
+        /// <summary>
+        /// Manages alliance treasury including member contributions, resource allocation, and emergency reserves.
+        /// Handles collective resource pooling for research, territory maintenance, and member assistance.
+        /// </summary>
+        /// <param name="allianceId">The alliance managing treasury</param>
+        /// <param name="treasuryTransaction">Resource deposits, withdrawals, or allocations</param>
+        /// <param name="authorizingPlayerId">The leader authorizing the transaction</param>
+        /// <param name="kingdomId">The kingdom context for the operation</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Updated alliance with new treasury status</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid or player lacks authority</exception>
+        /// <exception cref="InvalidOperationException">Thrown when treasury transaction violates policies</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<Alliance> ManageAllianceTreasuryAsync(int allianceId, object treasuryTransaction, int authorizingPlayerId,
+            int kingdomId, CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Facilitates resource sharing between alliance members including loans, gifts, and emergency assistance.
+        /// Tracks member-to-member resource transfers and alliance-sponsored support programs.
+        /// </summary>
+        /// <param name="allianceId">The alliance facilitating resource sharing</param>
+        /// <param name="senderId">The member providing resources</param>
+        /// <param name="recipientId">The member receiving resources</param>
+        /// <param name="resourceTransfer">Resources being transferred</param>
+        /// <param name="transferType">Gift, loan, or emergency assistance</param>
+        /// <param name="kingdomId">The kingdom context for the operation</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Updated alliance with recorded resource transfer</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid or members are ineligible</exception>
+        /// <exception cref="InvalidOperationException">Thrown when resource transfer violates policies</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<Alliance> FacilitateResourceSharingAsync(int allianceId, int senderId, int recipientId,
+            object resourceTransfer, string transferType, int kingdomId, CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Gets alliance economic analytics including resource generation efficiency, member contribution patterns,
+        /// treasury health, and economic competitiveness compared to other alliances.
+        /// </summary>
+        /// <param name="allianceId">The alliance to analyze</param>
+        /// <param name="analysisTimeframe">Time period for economic analysis</param>
+        /// <param name="kingdomId">The kingdom context for the operation</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Comprehensive economic analysis with trends and recommendations</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<object> GetAllianceEconomicAnalyticsAsync(int allianceId, TimeSpan analysisTimeframe, int kingdomId,
+            CancellationToken cancellationToken = default);
+
+        #endregion
+
+        #region Alliance Analytics and Performance
+
+        /// <summary>
+        /// Gets comprehensive alliance performance metrics including member satisfaction, military effectiveness,
+        /// economic efficiency, territorial control, and social engagement for leadership analysis.
+        /// </summary>
+        /// <param name="allianceId">The alliance to analyze</param>
+        /// <param name="kingdomId">The kingdom context for the operation</param>
+        /// <param name="analysisDepth">Surface-level, detailed, or comprehensive analysis</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Detailed alliance performance analytics with actionable insights</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<object> GetAlliancePerformanceMetricsAsync(int allianceId, int kingdomId, string analysisDepth = "detailed",
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Gets alliance ranking and competitive position within the kingdom including power rankings,
+        /// territorial control, research advancement, and member satisfaction benchmarks.
+        /// </summary>
+        /// <param name="kingdomId">The kingdom to generate rankings for</param>
+        /// <param name="rankingCategory">The metric to rank by (power, territory, research, satisfaction)</param>
+        /// <param name="topCount">Number of top alliances to return</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Alliance rankings with detailed competitive analysis</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<IEnumerable<(Alliance Alliance, object RankingValue, int Rank, object CompetitiveAnalysis)>> GetAllianceRankingsAsync(
+            int kingdomId, string rankingCategory, int topCount = 50, CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Generates alliance health report identifying potential issues like leadership conflicts,
+        /// member dissatisfaction, resource shortages, or strategic vulnerabilities requiring attention.
+        /// </summary>
+        /// <param name="allianceId">The alliance to assess</param>
+        /// <param name="kingdomId">The kingdom context for the operation</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Alliance health assessment with priority action items</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<object> GenerateAllianceHealthReportAsync(int allianceId, int kingdomId,
+            CancellationToken cancellationToken = default);
+
+        #endregion
+
+        #region Democratic Host Selection for KvK
+
+        /// <summary>
+        /// Initiates democratic host selection process for KvK events where alliance members vote
+        /// for leadership roles during kingdom events. Ensures fair representation and member engagement.
+        /// </summary>
+        /// <param name="allianceId">The alliance participating in host selection</param>
+        /// <param name="kvkEventId">The KvK event requiring host selection</param>
+        /// <param name="availableRoles">Leadership roles available during the event</param>
+        /// <param name="kingdomId">The kingdom context for the operation</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Host selection voting configuration with candidate nominations</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid or alliance not eligible</exception>
+        /// <exception cref="InvalidOperationException">Thrown when host selection cannot be initiated</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<object> InitiateKvKHostSelectionAsync(int allianceId, int kvkEventId, IEnumerable<string> availableRoles,
+            int kingdomId, CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Processes votes for alliance representatives in KvK host selection, ensuring democratic
+        /// participation and transparent selection of alliance members for kingdom leadership roles.
+        /// </summary>
+        /// <param name="allianceId">The alliance conducting voting</param>
+        /// <param name="votingMemberId">The member casting their vote</param>
+        /// <param name="voteConfiguration">Vote selections for available roles</param>
+        /// <param name="kingdomId">The kingdom context for the operation</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Updated voting status with member participation tracking</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid or member ineligible to vote</exception>
+        /// <exception cref="InvalidOperationException">Thrown when voting fails due to timing or eligibility</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<object> ProcessKvKHostVoteAsync(int allianceId, int votingMemberId, object voteConfiguration,
+            int kingdomId, CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Finalizes KvK host selection results, appointing alliance representatives to kingdom roles
+        /// and establishing authority delegation for the duration of the KvK event.
+        /// </summary>
+        /// <param name="allianceId">The alliance finalizing host selection</param>
+        /// <param name="selectionResults">Voting results and selected representatives</param>
+        /// <param name="kingdomId">The kingdom context for the operation</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Updated alliance with appointed KvK representatives and authority delegation</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid or results are contested</exception>
+        /// <exception cref="InvalidOperationException">Thrown when host selection finalization fails</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<Alliance> FinalizeKvKHostSelectionAsync(int allianceId, object selectionResults, int kingdomId,
+            CancellationToken cancellationToken = default);
+
+        #endregion
+    }
+}

ShadowedRealmsMobile/src/server/ShadowedRealms.Core/Interfaces/Repositories/ICombatLogRepository.cs

@@ -0,0 +1,522 @@
+/*
+ * File: /src/server/ShadowedRealms.Core/Interfaces/Repositories/ICombatLogRepository.cs
+ * Created: 2025-10-19
+ * Last Modified: 2025-10-19
+ * Description: Combat log repository interface defining combat-specific data access operations.
+ *              Handles field interception combat, battle resolution, KvK events, stealth mechanics,
+ *              dragon integration, speed limitations, and attack classifications. Core innovation
+ *              is the field interception system where defenders can meet attackers before they reach castles.
+ * Last Edit Notes: Initial implementation with field interception, battle resolution, KvK mechanics, and combat analytics.
+ */
+
+using ShadowedRealms.Core.Models;
+using ShadowedRealms.Core.Models.Combat;
+using System.Linq.Expressions;
+
+namespace ShadowedRealms.Core.Interfaces.Repositories
+{
+    /// <summary>
+    /// Repository interface for CombatLog entity operations, providing comprehensive combat system management,
+    /// field interception mechanics, battle resolution, KvK event tracking, and combat analytics.
+    /// Core innovation: Field interception system allows defenders to meet attackers before castle sieges.
+    /// </summary>
+    public interface ICombatLogRepository : IRepository<CombatLog, int>
+    {
+        #region Field Interception System (Core Innovation)
+
+        /// <summary>
+        /// Creates a field interception combat engagement where defenders meet attackers before they reach the target castle.
+        /// CORE INNOVATION: Allows strategic defensive positioning and prevents inevitable castle sieges.
+        /// </summary>
+        /// <param name="attackingPlayerId">The player initiating the attack</param>
+        /// <param name="defendingPlayerId">The player defending (can intercept in the field)</param>
+        /// <param name="interceptionCoordinates">Where the field battle takes place</param>
+        /// <param name="attackingForce">Attacking army composition and equipment</param>
+        /// <param name="defendingForce">Defending army composition and equipment</param>
+        /// <param name="kingdomId">The kingdom context for the combat</param>
+        /// <param name="combatConfiguration">Battle parameters, terrain effects, and special conditions</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Created combat log with field interception battle results</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid or interception is not allowed</exception>
+        /// <exception cref="InvalidOperationException">Thrown when field interception cannot be initiated</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<CombatLog> CreateFieldInterceptionCombatAsync(int attackingPlayerId, int defendingPlayerId,
+            (int X, int Y) interceptionCoordinates, object attackingForce, object defendingForce, int kingdomId,
+            object combatConfiguration, CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Validates if field interception is possible based on army positions, movement speeds, timing windows,
+        /// and strategic positioning. Calculates interception probability and optimal positioning.
+        /// </summary>
+        /// <param name="attackingPlayerId">The attacking player</param>
+        /// <param name="defendingPlayerId">The potential intercepting player</param>
+        /// <param name="targetCoordinates">The original target of the attack</param>
+        /// <param name="kingdomId">The kingdom context for validation</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Interception feasibility analysis with optimal positioning recommendations</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<(bool CanIntercept, double InterceptionProbability, (int X, int Y)[] OptimalPositions, TimeSpan TimeWindow)>
+            ValidateFieldInterceptionAsync(int attackingPlayerId, int defendingPlayerId, (int X, int Y) targetCoordinates,
+            int kingdomId, CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Gets active field interception opportunities for alliance members and kingdom defenders.
+        /// Identifies incoming attacks that can be intercepted and calculates strategic value.
+        /// </summary>
+        /// <param name="defendingPlayerId">The player looking for interception opportunities</param>
+        /// <param name="searchRadius">Radius around player to search for interception opportunities</param>
+        /// <param name="kingdomId">The kingdom context for the search</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Available interception opportunities with strategic analysis</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<IEnumerable<(object AttackDetails, double StrategicValue, TimeSpan TimeToIntercept)>>
+            GetFieldInterceptionOpportunitiesAsync(int defendingPlayerId, int searchRadius, int kingdomId,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Processes field interception battle resolution using statistical combat system with attack/defense/health
+        /// calculations, damage modifiers, dragon bonuses, and equipment effects.
+        /// </summary>
+        /// <param name="combatLogId">The combat engagement to resolve</param>
+        /// <param name="battleParameters">Combat calculations, random factors, and environmental effects</param>
+        /// <param name="kingdomId">The kingdom context for the battle</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Updated combat log with battle resolution and casualty reports</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid or combat already resolved</exception>
+        /// <exception cref="InvalidOperationException">Thrown when battle resolution fails</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<CombatLog> ResolveFieldInterceptionBattleAsync(int combatLogId, object battleParameters, int kingdomId,
+            CancellationToken cancellationToken = default);
+
+        #endregion
+
+        #region Attack Classification System
+
+        /// <summary>
+        /// Classifies attack types based on army composition, target selection, and strategic intent.
+        /// Ranges from Lightning Raids (unrestricted) to Castle Sieges (fully restricted by field interception).
+        /// </summary>
+        /// <param name="attackingPlayerId">The attacking player</param>
+        /// <param name="targetCoordinates">The target location</param>
+        /// <param name="armyComposition">Army size, composition, and equipment</param>
+        /// <param name="kingdomId">The kingdom context for classification</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Attack classification with interception rules and restrictions</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<(string AttackType, string[] InterceptionRules, double VulnerabilityFactor)> ClassifyAttackTypeAsync(
+            int attackingPlayerId, (int X, int Y) targetCoordinates, object armyComposition, int kingdomId,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Gets combat logs filtered by attack classification for strategic analysis and defensive planning.
+        /// Helps identify attack patterns and defensive effectiveness by attack type.
+        /// </summary>
+        /// <param name="attackType">The attack classification to filter by</param>
+        /// <param name="kingdomId">The kingdom context for the search</param>
+        /// <param name="timeRange">Time period to analyze</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Combat logs matching the attack classification</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<IEnumerable<CombatLog>> GetCombatLogsByAttackTypeAsync(string attackType, int kingdomId, TimeSpan timeRange,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Analyzes attack effectiveness by classification, identifying successful strategies and defensive gaps.
+        /// Provides insights for both offensive planning and defensive improvements.
+        /// </summary>
+        /// <param name="kingdomId">The kingdom to analyze</param>
+        /// <param name="analysisTimeframe">Time period for analysis</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Attack effectiveness analysis by classification with strategic recommendations</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<object> AnalyzeAttackEffectivenessByTypeAsync(int kingdomId, TimeSpan analysisTimeframe,
+            CancellationToken cancellationToken = default);
+
+        #endregion
+
+        #region Speed Limitations and March Mechanics
+
+        /// <summary>
+        /// Calculates march times between coordinates considering minimum march times, diminishing returns on speed,
+        /// terrain effects, alliance territory bonuses, and temporary speed modifications.
+        /// </summary>
+        /// <param name="startCoordinates">Starting position</param>
+        /// <param name="endCoordinates">Destination position</param>
+        /// <param name="armyComposition">Army affecting march speed</param>
+        /// <param name="playerId">Player for speed bonuses calculation</param>
+        /// <param name="kingdomId">The kingdom context for calculations</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>March time calculations with speed factors and arrival prediction</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<(TimeSpan MarchTime, TimeSpan MinimumTime, double SpeedModifier, DateTime EstimatedArrival)>
+            CalculateMarchTimeAsync((int X, int Y) startCoordinates, (int X, int Y) endCoordinates,
+            object armyComposition, int playerId, int kingdomId, CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Validates march legality based on speed limitations, grace periods, cooldown restrictions,
+        /// and movement rule violations. Prevents exploitation of speed mechanics.
+        /// </summary>
+        /// <param name="playerId">The player attempting the march</param>
+        /// <param name="marchConfiguration">March details including target, army, and timing</param>
+        /// <param name="kingdomId">The kingdom context for validation</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>March validation result with restriction details and cooldown information</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<(bool IsAllowed, string[] Restrictions, TimeSpan? RequiredWait)> ValidateMarchLegalityAsync(
+            int playerId, object marchConfiguration, int kingdomId, CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Records march history for speed limitation enforcement and pattern analysis.
+        /// Tracks march frequency, destinations, and timing to prevent exploitation.
+        /// </summary>
+        /// <param name="playerId">The player making the march</param>
+        /// <param name="marchDetails">Complete march information</param>
+        /// <param name="kingdomId">The kingdom context for recording</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Updated march history with timing validation</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="InvalidOperationException">Thrown when march recording fails</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<object> RecordMarchHistoryAsync(int playerId, object marchDetails, int kingdomId,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Gets march analytics for players including frequency patterns, preferred targets,
+        /// timing strategies, and effectiveness metrics for behavioral analysis.
+        /// </summary>
+        /// <param name="playerId">The player to analyze</param>
+        /// <param name="kingdomId">The kingdom context for analysis</param>
+        /// <param name="analysisTimeframe">Time period for march analysis</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Comprehensive march behavior analysis</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<object> GetPlayerMarchAnalyticsAsync(int playerId, int kingdomId, TimeSpan analysisTimeframe,
+            CancellationToken cancellationToken = default);
+
+        #endregion
+
+        #region Stealth and Route Planning
+
+        /// <summary>
+        /// Creates stealth march plans with hidden routes and timing to avoid detection and interception.
+        /// Balances free strategic planning with premium convenience options for route optimization.
+        /// </summary>
+        /// <param name="playerId">The player planning the stealth march</param>
+        /// <param name="targetCoordinates">The intended target</param>
+        /// <param name="stealthConfiguration">Stealth parameters and route preferences</param>
+        /// <param name="kingdomId">The kingdom context for planning</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Stealth march plan with route options and detection probability</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid or stealth not available</exception>
+        /// <exception cref="InvalidOperationException">Thrown when stealth planning fails</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<object> CreateStealthMarchPlanAsync(int playerId, (int X, int Y) targetCoordinates,
+            object stealthConfiguration, int kingdomId, CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Detects stealth marches based on intelligence networks, scout reports, and detection systems.
+        /// Provides early warning for defended territories and alliance coordination.
+        /// </summary>
+        /// <param name="defendingPlayerId">The player with detection capabilities</param>
+        /// <param name="detectionRadius">Area to scan for stealth marches</param>
+        /// <param name="kingdomId">The kingdom context for detection</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Detected stealth marches with confidence levels and estimated targets</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<IEnumerable<(object MarchDetails, double DetectionConfidence, (int X, int Y) EstimatedTarget)>>
+            DetectStealthMarchesAsync(int defendingPlayerId, int detectionRadius, int kingdomId,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Validates route planning options based on player access level (free vs premium features).
+        /// Ensures skill-based alternatives exist while providing convenience options for premium users.
+        /// </summary>
+        /// <param name="playerId">The player planning routes</param>
+        /// <param name="routePreferences">Desired route characteristics</param>
+        /// <param name="kingdomId">The kingdom context for validation</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Available route planning options with feature access levels</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<(object[] FreeOptions, object[] PremiumOptions, string[] SkillBasedAlternatives)>
+            ValidateRoutePlanningAccessAsync(int playerId, object routePreferences, int kingdomId,
+            CancellationToken cancellationToken = default);
+
+        #endregion
+
+        #region Dragon Integration and Combat Bonuses
+
+        /// <summary>
+        /// Applies dragon bonuses to combat calculations including skill-based buffs, equipment effects,
+        /// and evolution bonuses. Dragons must accompany armies and provide strategic advantages.
+        /// </summary>
+        /// <param name="combatLogId">The combat engagement to apply dragon bonuses to</param>
+        /// <param name="attackingDragonConfiguration">Attacking player's dragon setup</param>
+        /// <param name="defendingDragonConfiguration">Defending player's dragon setup</param>
+        /// <param name="kingdomId">The kingdom context for the combat</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Updated combat log with dragon bonus calculations</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid or dragons not present</exception>
+        /// <exception cref="InvalidOperationException">Thrown when dragon bonus application fails</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<CombatLog> ApplyDragonBonusesToCombatAsync(int combatLogId, object attackingDragonConfiguration,
+            object defendingDragonConfiguration, int kingdomId, CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Validates dragon participation in combat based on army composition, dragon stamina,
+        /// skill compatibility, and equipment requirements for combat engagement.
+        /// </summary>
+        /// <param name="playerId">The player with the dragon</param>
+        /// <param name="dragonConfiguration">Dragon skills, equipment, and status</param>
+        /// <param name="armyComposition">Army the dragon will accompany</param>
+        /// <param name="kingdomId">The kingdom context for validation</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Dragon participation validation with skill effectiveness prediction</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<(bool CanParticipate, double EffectivenessModifier, string[] SkillBonuses, string[] Restrictions)>
+            ValidateDragonParticipationAsync(int playerId, object dragonConfiguration, object armyComposition,
+            int kingdomId, CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Gets dragon combat performance analytics including skill effectiveness, equipment impact,
+        /// evolution benefits, and strategic value in different combat scenarios.
+        /// </summary>
+        /// <param name="playerId">The player to analyze dragon performance for</param>
+        /// <param name="kingdomId">The kingdom context for analysis</param>
+        /// <param name="analysisTimeframe">Time period for dragon performance analysis</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Dragon performance analytics with optimization recommendations</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<object> GetDragonCombatAnalyticsAsync(int playerId, int kingdomId, TimeSpan analysisTimeframe,
+            CancellationToken cancellationToken = default);
+
+        #endregion
+
+        #region KvK Combat Events
+
+        /// <summary>
+        /// Creates large-scale KvK combat events involving multiple kingdoms, alliances, and coalition forces.
+        /// Handles complex battle scenarios with kingdom vs kingdom mechanics and territory control.
+        /// </summary>
+        /// <param name="participatingKingdoms">Kingdoms involved in the KvK combat</param>
+        /// <param name="eventType">Type of KvK event (3-kingdom war, alliance conquest, etc.)</param>
+        /// <param name="battlefieldConfiguration">Terrain, objectives, and victory conditions</param>
+        /// <param name="coalitionArrangements">Alliance coalitions and their battle formations</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Created KvK combat event with initial battle state</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid or kingdoms ineligible</exception>
+        /// <exception cref="InvalidOperationException">Thrown when KvK event creation fails</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<CombatLog> CreateKvKCombatEventAsync(IEnumerable<int> participatingKingdoms, string eventType,
+            object battlefieldConfiguration, object coalitionArrangements, CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Tracks KvK battle progression including territory control changes, casualty reports,
+        /// strategic objective completion, and coalition performance metrics.
+        /// </summary>
+        /// <param name="kvkCombatId">The KvK combat event to track</param>
+        /// <param name="battleUpdates">Current battle state and changes</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Updated KvK combat log with battle progression</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid or combat not found</exception>
+        /// <exception cref="InvalidOperationException">Thrown when battle tracking fails</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<CombatLog> TrackKvKBattleProgressionAsync(int kvkCombatId, object battleUpdates,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Resolves KvK combat events with multiple victory paths including military dominance,
+        /// economic control, diplomatic success, and technological advancement.
+        /// </summary>
+        /// <param name="kvkCombatId">The KvK combat event to resolve</param>
+        /// <param name="victoryConditions">Conditions met for victory determination</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Resolved KvK combat log with victory outcomes and rewards distribution</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid or combat already resolved</exception>
+        /// <exception cref="InvalidOperationException">Thrown when KvK resolution fails</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<CombatLog> ResolveKvKCombatEventAsync(int kvkCombatId, object victoryConditions,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Gets KvK combat history for kingdoms including participation records, performance metrics,
+        /// victory/defeat ratios, and strategic lessons learned for future matchmaking.
+        /// </summary>
+        /// <param name="kingdomId">The kingdom to get KvK history for</param>
+        /// <param name="historyTimeframe">Time period for historical analysis</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>KvK combat history with performance trends and strategic insights</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<object> GetKvKCombatHistoryAsync(int kingdomId, TimeSpan historyTimeframe,
+            CancellationToken cancellationToken = default);
+
+        #endregion
+
+        #region Forest Barrier and Banishment Mechanics
+
+        /// <summary>
+        /// Applies forest barrier speed penalties (50% reduction) for players crossing into contested forest zones
+        /// during KvK events. Handles terrain-based movement restrictions and strategic positioning.
+        /// </summary>
+        /// <param name="playerId">The player entering forest barriers</param>
+        /// <param name="forestCoordinates">The forest zone coordinates</param>
+        /// <param name="crossingConfiguration">Crossing attempt details and timing</param>
+        /// <param name="kingdomId">The kingdom context for the crossing</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Forest crossing result with speed penalties and strategic implications</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid or crossing not allowed</exception>
+        /// <exception cref="InvalidOperationException">Thrown when forest crossing fails</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<object> ApplyForestBarrierPenaltyAsync(int playerId, (int X, int Y) forestCoordinates,
+            object crossingConfiguration, int kingdomId, CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Processes castle banishment for players who lose battles in contested forest zones.
+        /// Handles forced teleportation, temporary restrictions, and recovery mechanics.
+        /// </summary>
+        /// <param name="banishedPlayerId">The player being banished from their castle</param>
+        /// <param name="banishmentTrigger">Combat result or event causing banishment</param>
+        /// <param name="banishmentDuration">How long the banishment lasts</param>
+        /// <param name="kingdomId">The kingdom context for banishment</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Banishment result with recovery options and timeline</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid or banishment not justified</exception>
+        /// <exception cref="InvalidOperationException">Thrown when banishment processing fails</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<object> ProcessCastleBanishmentAsync(int banishedPlayerId, object banishmentTrigger,
+            TimeSpan banishmentDuration, int kingdomId, CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Gets forest zone control status including alliance territorial claims, contested areas,
+        /// and strategic resource locations that trigger barrier mechanics during conflicts.
+        /// </summary>
+        /// <param name="forestZoneId">The forest zone to analyze</param>
+        /// <param name="kingdomId">The kingdom context for analysis</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Forest zone control analysis with territorial disputes and strategic value</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<object> GetForestZoneControlStatusAsync(int forestZoneId, int kingdomId,
+            CancellationToken cancellationToken = default);
+
+        #endregion
+
+        #region Combat Analytics and Intelligence
+
+        /// <summary>
+        /// Gets comprehensive combat analytics for players including win/loss ratios, effectiveness by attack type,
+        /// field interception success rates, and strategic pattern analysis for performance improvement.
+        /// </summary>
+        /// <param name="playerId">The player to analyze</param>
+        /// <param name="kingdomId">The kingdom context for analysis</param>
+        /// <param name="analysisTimeframe">Time period for combat analysis</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Detailed combat performance analytics with improvement recommendations</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<object> GetPlayerCombatAnalyticsAsync(int playerId, int kingdomId, TimeSpan analysisTimeframe,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Generates combat intelligence reports for alliances including threat assessment, enemy patterns,
+        /// strategic vulnerabilities, and recommended defensive posturing for alliance coordination.
+        /// </summary>
+        /// <param name="allianceId">The alliance requesting intelligence</param>
+        /// <param name="kingdomId">The kingdom context for intelligence</param>
+        /// <param name="intelligenceScope">Local threats, kingdom-wide, or KvK intelligence</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Combat intelligence report with threat analysis and strategic recommendations</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<object> GenerateAllianceCombatIntelligenceAsync(int allianceId, int kingdomId, string intelligenceScope,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Gets kingdom combat statistics including overall military activity, power distribution,
+        /// alliance conflicts, and readiness for KvK events for administrative and strategic planning.
+        /// </summary>
+        /// <param name="kingdomId">The kingdom to analyze</param>
+        /// <param name="statisticsTimeframe">Time period for statistical analysis</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Kingdom combat statistics with military readiness assessment</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<object> GetKingdomCombatStatisticsAsync(int kingdomId, TimeSpan statisticsTimeframe,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Analyzes combat effectiveness of different troop compositions, equipment combinations,
+        /// and strategic approaches to provide data-driven optimization recommendations.
+        /// </summary>
+        /// <param name="combatParameters">Combat scenarios and variables to analyze</param>
+        /// <param name="kingdomId">The kingdom context for analysis</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Combat effectiveness analysis with optimization recommendations</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<object> AnalyzeCombatEffectivenessAsync(object combatParameters, int kingdomId,
+            CancellationToken cancellationToken = default);
+
+        #endregion
+
+        #region Battle Resolution and Statistical Combat
+
+        /// <summary>
+        /// Processes statistical combat resolution using attack/defense/health calculations with damage modifiers,
+        /// critical hits, armor penetration, and tactical bonuses for realistic battle outcomes.
+        /// </summary>
+        /// <param name="combatLogId">The combat engagement to resolve</param>
+        /// <param name="combatParameters">All factors affecting battle outcome</param>
+        /// <param name="kingdomId">The kingdom context for resolution</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Resolved combat log with detailed battle results and casualty breakdown</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid or combat already resolved</exception>
+        /// <exception cref="InvalidOperationException">Thrown when battle resolution fails</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<CombatLog> ResolveStatisticalCombatAsync(int combatLogId, object combatParameters, int kingdomId,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Calculates troop effectiveness modifiers based on tier differences, equipment quality,
+        /// research bonuses, alliance support, and environmental factors for accurate combat predictions.
+        /// </summary>
+        /// <param name="attackingArmy">Attacking force composition and bonuses</param>
+        /// <param name="defendingArmy">Defending force composition and bonuses</param>
+        /// <param name="battleConditions">Environmental and situational factors</param>
+        /// <param name="kingdomId">The kingdom context for calculations</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Combat effectiveness calculations with modifier breakdown</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<object> CalculateTroopEffectivenessAsync(object attackingArmy, object defendingArmy,
+            object battleConditions, int kingdomId, CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Simulates combat outcomes for strategic planning without actually conducting battles.
+        /// Provides probability distributions and expected results for tactical decision-making.
+        /// </summary>
+        /// <param name="simulationParameters">Hypothetical combat scenarios to simulate</param>
+        /// <param name="simulationCount">Number of simulation runs for statistical accuracy</param>
+        /// <param name="kingdomId">The kingdom context for simulation</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Combat simulation results with probability analysis and outcome predictions</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<object> SimulateCombatOutcomesAsync(object simulationParameters, int simulationCount, int kingdomId,
+            CancellationToken cancellationToken = default);
+
+        #endregion
+    }
+}

ShadowedRealmsMobile/src/server/ShadowedRealms.Core/Interfaces/Repositories/IKingdomRepository.cs

@@ -0,0 +1,358 @@
+/*
+ * File: /src/server/ShadowedRealms.Core/Interfaces/Repositories/IKingdomRepository.cs
+ * Created: 2025-10-19
+ * Last Modified: 2025-10-19
+ * Description: Kingdom repository interface defining kingdom-specific data access operations.
+ *              Handles kingdom lifecycle, population management, KvK events, merger systems,
+ *              and democratic political mechanics. Since Kingdom is the root scoping entity,
+ *              this interface includes special operations for cross-kingdom queries when needed.
+ * Last Edit Notes: Initial implementation with population management, KvK systems, merger mechanics, and political operations.
+ */
+
+using ShadowedRealms.Core.Models;
+using ShadowedRealms.Core.Models.Kingdom;
+using System.Linq.Expressions;
+
+namespace ShadowedRealms.Core.Interfaces.Repositories
+{
+    /// <summary>
+    /// Repository interface for Kingdom entity operations, providing kingdom lifecycle management,
+    /// population control, KvK event coordination, merger systems, and democratic political mechanics.
+    /// This is the root repository that enables cross-kingdom operations when specifically needed.
+    /// </summary>
+    public interface IKingdomRepository : IRepository<Kingdom, int>
+    {
+        #region Kingdom Lifecycle Management
+
+        /// <summary>
+        /// Creates a new kingdom with initial configuration and assigns it the next available kingdom number.
+        /// Automatically sets up default political structure and resource allocation systems.
+        /// </summary>
+        /// <param name="kingdomName">The name for the new kingdom</param>
+        /// <param name="serverRegion">The server region where the kingdom will be hosted</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>The newly created kingdom with initial configuration</returns>
+        /// <exception cref="ArgumentException">Thrown when kingdomName is invalid or serverRegion is not supported</exception>
+        /// <exception cref="InvalidOperationException">Thrown when kingdom creation fails due to system constraints</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<Kingdom> CreateNewKingdomAsync(string kingdomName, string serverRegion,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Gets all kingdoms that are currently accepting new players based on population thresholds.
+        /// Returns kingdoms with population below the maximum capacity (1,500 players) sorted by creation date.
+        /// </summary>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Available kingdoms for new player registration</returns>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<IEnumerable<Kingdom>> GetAvailableKingdomsForNewPlayersAsync(CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Gets the newest kingdom that has space for new players, creating one if none exist.
+        /// This is used for the default kingdom assignment when players don't choose manually.
+        /// </summary>
+        /// <param name="serverRegion">The preferred server region for kingdom selection</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>The newest available kingdom or a newly created one</returns>
+        /// <exception cref="ArgumentException">Thrown when serverRegion is invalid</exception>
+        /// <exception cref="InvalidOperationException">Thrown when kingdom selection/creation fails</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<Kingdom> GetNewestAvailableKingdomAsync(string serverRegion,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Archives a kingdom that no longer has active players or has been merged into another kingdom.
+        /// Preserves historical data while removing the kingdom from active matchmaking and operations.
+        /// </summary>
+        /// <param name="kingdomId">The ID of the kingdom to archive</param>
+        /// <param name="archiveReason">The reason for archiving (merger, inactivity, etc.)</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>True if kingdom was archived successfully</returns>
+        /// <exception cref="ArgumentException">Thrown when kingdomId is invalid or kingdom cannot be archived</exception>
+        /// <exception cref="InvalidOperationException">Thrown when kingdom has active players or pending operations</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<bool> ArchiveKingdomAsync(int kingdomId, string archiveReason,
+            CancellationToken cancellationToken = default);
+
+        #endregion
+
+        #region Population Management
+
+        /// <summary>
+        /// Gets the current population count for a specific kingdom including active and inactive players.
+        /// Used for kingdom capacity management and merger eligibility determination.
+        /// </summary>
+        /// <param name="kingdomId">The kingdom to get population for</param>
+        /// <param name="includeInactive">Whether to include players who haven't logged in recently</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Current population statistics for the kingdom</returns>
+        /// <exception cref="ArgumentException">Thrown when kingdomId is invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<(int ActivePlayers, int InactivePlayers, int TotalPlayers)> GetKingdomPopulationAsync(int kingdomId,
+            bool includeInactive = false, CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Gets kingdoms that are eligible for population-based merger based on low active player counts.
+        /// Returns kingdoms with fewer than the minimum viable population (typically 300-500 active players).
+        /// </summary>
+        /// <param name="minimumViablePopulation">The minimum population threshold for kingdom viability</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Kingdoms eligible for merger due to low population</returns>
+        /// <exception cref="ArgumentException">Thrown when minimumViablePopulation is invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<IEnumerable<Kingdom>> GetKingdomsEligibleForMergerAsync(int minimumViablePopulation = 400,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Updates the population statistics for a kingdom, typically called when players join/leave.
+        /// Automatically triggers kingdom capacity events when thresholds are reached.
+        /// </summary>
+        /// <param name="kingdomId">The kingdom to update</param>
+        /// <param name="populationChange">The change in population (positive for joins, negative for leaves)</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Updated kingdom with new population statistics</returns>
+        /// <exception cref="ArgumentException">Thrown when kingdomId is invalid</exception>
+        /// <exception cref="InvalidOperationException">Thrown when population change would violate system constraints</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<Kingdom> UpdateKingdomPopulationAsync(int kingdomId, int populationChange,
+            CancellationToken cancellationToken = default);
+
+        #endregion
+
+        #region KvK Event Management
+
+        /// <summary>
+        /// Gets kingdoms that are eligible for KvK matchmaking based on power levels, participation history,
+        /// and time zone compatibility. Uses multi-dimensional analysis beyond raw power comparison.
+        /// </summary>
+        /// <param name="targetKingdomId">The kingdom requesting matchmaking</param>
+        /// <param name="eventType">The type of KvK event being organized</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Kingdoms eligible for KvK matchmaking with compatibility scores</returns>
+        /// <exception cref="ArgumentException">Thrown when targetKingdomId is invalid or eventType is unsupported</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<IEnumerable<(Kingdom Kingdom, double CompatibilityScore)>> GetKvKEligibleKingdomsAsync(int targetKingdomId,
+            string eventType, CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Creates a new KvK event linking multiple kingdoms and initializes event-specific data structures.
+        /// Sets up coalition systems, territory assignments, and victory condition tracking.
+        /// </summary>
+        /// <param name="participatingKingdomIds">The kingdoms participating in the event</param>
+        /// <param name="eventType">The type of KvK event (3-kingdom, alliance wars, etc.)</param>
+        /// <param name="startDate">When the event begins</param>
+        /// <param name="duration">How long the event lasts</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>The created KvK event with initial configuration</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid or kingdoms are ineligible</exception>
+        /// <exception cref="InvalidOperationException">Thrown when event creation fails due to system constraints</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<object> CreateKvKEventAsync(IEnumerable<int> participatingKingdomIds, string eventType,
+            DateTime startDate, TimeSpan duration, CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Gets the current KvK events that a kingdom is participating in, including event status and performance metrics.
+        /// Returns both active events and recent historical events for context.
+        /// </summary>
+        /// <param name="kingdomId">The kingdom to get KvK events for</param>
+        /// <param name="includeHistorical">Whether to include completed events from the last 30 days</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>KvK events associated with the kingdom</returns>
+        /// <exception cref="ArgumentException">Thrown when kingdomId is invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<IEnumerable<object>> GetKingdomKvKEventsAsync(int kingdomId, bool includeHistorical = false,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Updates KvK performance metrics for a kingdom based on event participation and outcomes.
+        /// Affects future matchmaking and influences kingdom power ratings.
+        /// </summary>
+        /// <param name="kingdomId">The kingdom to update</param>
+        /// <param name="eventResult">The outcome of the KvK event</param>
+        /// <param name="participationMetrics">Detailed participation statistics</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Updated kingdom with new KvK performance data</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="InvalidOperationException">Thrown when update fails due to business rules</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<Kingdom> UpdateKvKPerformanceAsync(int kingdomId, object eventResult, object participationMetrics,
+            CancellationToken cancellationToken = default);
+
+        #endregion
+
+        #region Kingdom Merger System
+
+        /// <summary>
+        /// Initiates a merger proposal between two kingdoms, starting the democratic voting process.
+        /// Both kingdoms must vote to approve the merger for it to proceed.
+        /// </summary>
+        /// <param name="initiatingKingdomId">The kingdom proposing the merger</param>
+        /// <param name="targetKingdomId">The kingdom being invited to merge</param>
+        /// <param name="proposalReason">The rationale for the merger proposal</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>The merger proposal with voting configuration</returns>
+        /// <exception cref="ArgumentException">Thrown when kingdom IDs are invalid or kingdoms are ineligible</exception>
+        /// <exception cref="InvalidOperationException">Thrown when merger proposal cannot be created</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<object> ProposeMergerAsync(int initiatingKingdomId, int targetKingdomId, string proposalReason,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Gets kingdoms that are compatible for merger based on population, power levels, play styles,
+        /// and cultural compatibility. Used for suggesting merger partners to struggling kingdoms.
+        /// </summary>
+        /// <param name="kingdomId">The kingdom seeking merger partners</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Compatible kingdoms with compatibility scores and merger benefits analysis</returns>
+        /// <exception cref="ArgumentException">Thrown when kingdomId is invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<IEnumerable<(Kingdom Kingdom, double CompatibilityScore, string[] Benefits)>> GetMergerCompatibleKingdomsAsync(
+            int kingdomId, CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Executes an approved merger between two kingdoms, transferring all players, alliances, and resources
+        /// to the surviving kingdom while preserving historical data and alliance relationships.
+        /// </summary>
+        /// <param name="survivingKingdomId">The kingdom that will continue to exist</param>
+        /// <param name="mergingKingdomId">The kingdom that will be absorbed</param>
+        /// <param name="mergerConfiguration">Settings for how the merger should be executed</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>The updated surviving kingdom with merged population and resources</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid or merger is not approved</exception>
+        /// <exception cref="InvalidOperationException">Thrown when merger execution fails</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<Kingdom> ExecuteMergerAsync(int survivingKingdomId, int mergingKingdomId, object mergerConfiguration,
+            CancellationToken cancellationToken = default);
+
+        #endregion
+
+        #region Democratic Political System
+
+        /// <summary>
+        /// Gets the current royal court members for a kingdom including elected positions and appointed roles.
+        /// Returns the democratic leadership structure with terms, election dates, and approval ratings.
+        /// </summary>
+        /// <param name="kingdomId">The kingdom to get leadership for</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Current royal court structure with leadership details</returns>
+        /// <exception cref="ArgumentException">Thrown when kingdomId is invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<object> GetKingdomRoyalCourtAsync(int kingdomId, CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Initiates an election for a royal position within the kingdom's democratic system.
+        /// Sets up the voting process, candidate registration, and election timeline.
+        /// </summary>
+        /// <param name="kingdomId">The kingdom holding the election</param>
+        /// <param name="position">The royal position being elected (King, Chancellor, etc.)</param>
+        /// <param name="electionDuration">How long the election period lasts</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>The election configuration with voting details</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid or election cannot be held</exception>
+        /// <exception cref="InvalidOperationException">Thrown when election initiation fails</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<object> InitiateRoyalElectionAsync(int kingdomId, string position, TimeSpan electionDuration,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Updates the tax distribution settings for a kingdom based on royal court decisions.
+        /// Manages the 4% resource tax on conquered kingdoms and how it's distributed among citizens.
+        /// </summary>
+        /// <param name="kingdomId">The kingdom to update tax settings for</param>
+        /// <param name="taxDistributionRules">The new tax distribution configuration</param>
+        /// <param name="authorizingPlayerId">The royal court member authorizing the change</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Updated kingdom with new tax distribution settings</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid or player lacks authority</exception>
+        /// <exception cref="InvalidOperationException">Thrown when tax update fails due to business rules</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<Kingdom> UpdateTaxDistributionAsync(int kingdomId, object taxDistributionRules, int authorizingPlayerId,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Gets kingdoms that have conquered other kingdoms and are collecting the 4% resource tax.
+        /// Returns the tax collection status and distribution metrics for royal court oversight.
+        /// </summary>
+        /// <param name="kingdomId">The kingdom to get tax information for</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Tax collection and distribution details</returns>
+        /// <exception cref="ArgumentException">Thrown when kingdomId is invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<object> GetKingdomTaxStatusAsync(int kingdomId, CancellationToken cancellationToken = default);
+
+        #endregion
+
+        #region Analytics and Reporting
+
+        /// <summary>
+        /// Gets comprehensive kingdom statistics including population trends, economic metrics,
+        /// military strength, and social engagement data for administrative analysis.
+        /// </summary>
+        /// <param name="kingdomId">The kingdom to get statistics for</param>
+        /// <param name="timeRange">The time period to analyze (last 7 days, 30 days, etc.)</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Detailed kingdom analytics and performance metrics</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<object> GetKingdomAnalyticsAsync(int kingdomId, TimeSpan timeRange,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Gets kingdom performance metrics compared to other kingdoms in the same server region.
+        /// Provides percentile rankings for population, activity, military strength, and economic health.
+        /// </summary>
+        /// <param name="kingdomId">The kingdom to benchmark</param>
+        /// <param name="serverRegion">The server region for comparison</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Benchmark analysis with percentile rankings</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<object> GetKingdomBenchmarkAnalysisAsync(int kingdomId, string serverRegion,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Generates a kingdom health report identifying potential issues like population decline,
+        /// economic problems, or social tensions that might require intervention.
+        /// </summary>
+        /// <param name="kingdomId">The kingdom to analyze</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Kingdom health assessment with recommended actions</returns>
+        /// <exception cref="ArgumentException">Thrown when kingdomId is invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<object> GenerateKingdomHealthReportAsync(int kingdomId, CancellationToken cancellationToken = default);
+
+        #endregion
+
+        #region Cross-Kingdom Operations (Special Authorization)
+
+        /// <summary>
+        /// Gets all kingdoms in the system - SPECIAL METHOD that bypasses kingdom scoping.
+        /// Should only be used for administrative operations and system-level analytics.
+        /// Requires special authorization and should be logged for security audit.
+        /// </summary>
+        /// <param name="includeArchived">Whether to include archived kingdoms</param>
+        /// <param name="authorizingAdminId">The admin ID authorizing this cross-kingdom access</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>All kingdoms in the system</returns>
+        /// <exception cref="UnauthorizedAccessException">Thrown when admin authorization is invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<IEnumerable<Kingdom>> GetAllKingdomsAsync(bool includeArchived = false, int? authorizingAdminId = null,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Searches for kingdoms across all servers by name or other criteria.
+        /// SPECIAL METHOD for administrative use that bypasses normal kingdom scoping.
+        /// </summary>
+        /// <param name="searchCriteria">The search parameters</param>
+        /// <param name="authorizingAdminId">The admin ID authorizing this cross-kingdom search</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Kingdoms matching the search criteria across all servers</returns>
+        /// <exception cref="ArgumentNullException">Thrown when searchCriteria is null</exception>
+        /// <exception cref="UnauthorizedAccessException">Thrown when admin authorization is invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<IEnumerable<Kingdom>> SearchKingdomsGloballyAsync(object searchCriteria, int authorizingAdminId,
+            CancellationToken cancellationToken = default);
+
+        #endregion
+    }
+}

ShadowedRealmsMobile/src/server/ShadowedRealms.Core/Interfaces/Repositories/IPlayerRepository.cs

@@ -0,0 +1,562 @@
+/*
+ * File: /src/server/ShadowedRealms.Core/Interfaces/Repositories/IPlayerRepository.cs
+ * Created: 2025-10-19
+ * Last Modified: 2025-10-19
+ * Description: Player repository interface defining player-specific data access operations.
+ *              Handles castle progression, troop management, resource systems, VIP mechanics,
+ *              teleportation, research, equipment, and all core gameplay features for individual players.
+ *              All operations are kingdom-scoped to prevent cross-kingdom data access.
+ * Last Edit Notes: Initial implementation with comprehensive player mechanics, VIP system, teleportation, and gameplay features.
+ */
+
+using ShadowedRealms.Core.Models;
+using ShadowedRealms.Core.Models.Player;
+using System.Linq.Expressions;
+
+namespace ShadowedRealms.Core.Interfaces.Repositories
+{
+    /// <summary>
+    /// Repository interface for Player entity operations, providing comprehensive player lifecycle management,
+    /// castle progression, troop systems, resource management, VIP mechanics, and all core gameplay features.
+    /// All operations maintain kingdom-scoped security to prevent cross-kingdom data access.
+    /// </summary>
+    public interface IPlayerRepository : IRepository<Player, int>
+    {
+        #region Player Lifecycle and Authentication
+
+        /// <summary>
+        /// Creates a new player account within the specified kingdom with initial starting resources and configuration.
+        /// Automatically assigns starting position, beginner protection, and tutorial progress tracking.
+        /// </summary>
+        /// <param name="username">The player's chosen username (must be unique within kingdom)</param>
+        /// <param name="kingdomId">The kingdom where the player will be created</param>
+        /// <param name="startingConfiguration">Initial player setup including position and resources</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>The newly created player with starting configuration applied</returns>
+        /// <exception cref="ArgumentException">Thrown when username is invalid, taken, or kingdom is full</exception>
+        /// <exception cref="InvalidOperationException">Thrown when player creation fails due to system constraints</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<Player> CreateNewPlayerAsync(string username, int kingdomId, object startingConfiguration,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Gets a player by their username within the specified kingdom context.
+        /// Used for login authentication and player lookup operations.
+        /// </summary>
+        /// <param name="username">The player's username to search for</param>
+        /// <param name="kingdomId">The kingdom context for the search</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>The player if found within the kingdom, null otherwise</returns>
+        /// <exception cref="ArgumentException">Thrown when username is null/empty or kingdomId is invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<Player?> GetPlayerByUsernameAsync(string username, int kingdomId,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Updates the player's last login time and activity status for kingdom population management.
+        /// Tracks login streaks, daily rewards eligibility, and alliance participation metrics.
+        /// </summary>
+        /// <param name="playerId">The player to update</param>
+        /// <param name="kingdomId">The kingdom context for the operation</param>
+        /// <param name="loginMetrics">Additional login tracking data (IP, device, etc.)</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Updated player with new activity status</returns>
+        /// <exception cref="ArgumentException">Thrown when playerId or kingdomId is invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<Player> UpdatePlayerActivityAsync(int playerId, int kingdomId, object? loginMetrics = null,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Gets players who have been inactive beyond the specified threshold for kingdom health monitoring.
+        /// Used for identifying accounts at risk of abandonment and triggering retention campaigns.
+        /// </summary>
+        /// <param name="kingdomId">The kingdom to check for inactive players</param>
+        /// <param name="inactiveThreshold">How long without login constitutes inactive</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Inactive players within the kingdom</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<IEnumerable<Player>> GetInactivePlayersAsync(int kingdomId, TimeSpan inactiveThreshold,
+            CancellationToken cancellationToken = default);
+
+        #endregion
+
+        #region Castle and Progression Management
+
+        /// <summary>
+        /// Upgrades a player's castle level, automatically updating capacity limits, unlocking features,
+        /// and applying resource costs. Validates upgrade requirements and prerequisite building levels.
+        /// </summary>
+        /// <param name="playerId">The player upgrading their castle</param>
+        /// <param name="targetLevel">The target castle level (Launch cap: Level 30)</param>
+        /// <param name="kingdomId">The kingdom context for the operation</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Updated player with new castle level and unlocked features</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid or upgrade is not allowed</exception>
+        /// <exception cref="InvalidOperationException">Thrown when player lacks resources or prerequisites</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<Player> UpgradeCastleLevelAsync(int playerId, int targetLevel, int kingdomId,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Gets players within a specific castle level range for matchmaking, event organization,
+        /// and progression analytics. Supports alliance recruitment and KvK balancing.
+        /// </summary>
+        /// <param name="minLevel">Minimum castle level (inclusive)</param>
+        /// <param name="maxLevel">Maximum castle level (inclusive)</param>
+        /// <param name="kingdomId">The kingdom context for the search</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Players within the specified level range</returns>
+        /// <exception cref="ArgumentException">Thrown when level parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<IEnumerable<Player>> GetPlayersByLevelRangeAsync(int minLevel, int maxLevel, int kingdomId,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Gets the top players by castle level within the kingdom for leaderboards and recognition systems.
+        /// Includes progression speed metrics and recent advancement tracking.
+        /// </summary>
+        /// <param name="kingdomId">The kingdom to get top players from</param>
+        /// <param name="topCount">Number of top players to return</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Top players ranked by castle level and progression metrics</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<IEnumerable<Player>> GetTopPlayersByCastleLevelAsync(int kingdomId, int topCount = 100,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Updates building levels for a player's castle complex, validating prerequisites and resource costs.
+        /// Handles hospital, barracks, research facilities, and defensive structures.
+        /// </summary>
+        /// <param name="playerId">The player upgrading buildings</param>
+        /// <param name="buildingUpgrades">Dictionary of building types and target levels</param>
+        /// <param name="kingdomId">The kingdom context for the operation</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Updated player with new building levels</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid or upgrades violate rules</exception>
+        /// <exception cref="InvalidOperationException">Thrown when player lacks resources for upgrades</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<Player> UpdateBuildingLevelsAsync(int playerId, Dictionary<string, int> buildingUpgrades, int kingdomId,
+            CancellationToken cancellationToken = default);
+
+        #endregion
+
+        #region Troop and Military Management
+
+        /// <summary>
+        /// Updates a player's troop counts for specific tier and type, validating capacity limits
+        /// and training requirements. Handles T1-T13 troops with tier-specific restrictions.
+        /// </summary>
+        /// <param name="playerId">The player whose troops are being updated</param>
+        /// <param name="troopUpdates">Dictionary of troop types and count changes</param>
+        /// <param name="kingdomId">The kingdom context for the operation</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Updated player with new troop counts</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid or exceed capacity limits</exception>
+        /// <exception cref="InvalidOperationException">Thrown when troop updates violate game rules</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<Player> UpdateTroopCountsAsync(int playerId, Dictionary<string, int> troopUpdates, int kingdomId,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Gets players by military strength for alliance recruitment, KvK balancing, and threat assessment.
+        /// Calculates total military power including troops, dragons, and equipment bonuses.
+        /// </summary>
+        /// <param name="kingdomId">The kingdom to search within</param>
+        /// <param name="minimumPower">Minimum military power threshold</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Players meeting the minimum military power requirement</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<IEnumerable<Player>> GetPlayersByMilitaryStrengthAsync(int kingdomId, long minimumPower = 0,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Records troop losses from combat, hospital capacity management, and death mechanics.
+        /// Handles wounded vs killed troops, hospital overflow, and resurrection systems.
+        /// </summary>
+        /// <param name="playerId">The player who suffered losses</param>
+        /// <param name="troopLosses">Detailed breakdown of troop casualties</param>
+        /// <param name="combatContext">Combat information for loss calculations</param>
+        /// <param name="kingdomId">The kingdom context for the operation</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Updated player with recorded losses and hospital status</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="InvalidOperationException">Thrown when loss recording fails</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<Player> RecordTroopLossesAsync(int playerId, object troopLosses, object combatContext, int kingdomId,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Heals wounded troops in the hospital, consuming resources and time based on troop tier and count.
+        /// Supports instant healing with premium currency or time-based free healing.
+        /// </summary>
+        /// <param name="playerId">The player healing troops</param>
+        /// <param name="healingConfiguration">Healing method, troops to heal, and resource costs</param>
+        /// <param name="kingdomId">The kingdom context for the operation</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Updated player with healed troops and consumed resources</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid or player lacks resources</exception>
+        /// <exception cref="InvalidOperationException">Thrown when healing fails due to game rules</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<Player> HealWoundedTroopsAsync(int playerId, object healingConfiguration, int kingdomId,
+            CancellationToken cancellationToken = default);
+
+        #endregion
+
+        #region Resource Management
+
+        /// <summary>
+        /// Updates a player's resource counts (food, wood, stone, iron, gold) validating capacity limits
+        /// and storage building requirements. Handles resource production, consumption, and transfers.
+        /// </summary>
+        /// <param name="playerId">The player whose resources are being updated</param>
+        /// <param name="resourceChanges">Dictionary of resource types and amount changes (positive or negative)</param>
+        /// <param name="kingdomId">The kingdom context for the operation</param>
+        /// <param name="transactionReason">Reason for the resource change (for logging)</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Updated player with new resource amounts</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid or exceed storage limits</exception>
+        /// <exception cref="InvalidOperationException">Thrown when player lacks sufficient resources for deduction</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<Player> UpdateResourcesAsync(int playerId, Dictionary<string, long> resourceChanges, int kingdomId,
+            string transactionReason, CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Gets players with resource amounts within specified ranges for trading, alliance support,
+        /// and economic analysis. Supports finding players who can provide or need specific resources.
+        /// </summary>
+        /// <param name="kingdomId">The kingdom to search within</param>
+        /// <param name="resourceCriteria">Resource type and amount range criteria</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Players matching the resource criteria</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<IEnumerable<Player>> GetPlayersByResourceCriteriaAsync(int kingdomId, Dictionary<string, (long Min, long Max)> resourceCriteria,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Processes resource production for a player based on building levels, research bonuses, and time elapsed.
+        /// Calculates production rates, applies bonuses, and updates storage with capacity limits.
+        /// </summary>
+        /// <param name="playerId">The player generating resources</param>
+        /// <param name="productionDuration">Time period for resource generation</param>
+        /// <param name="kingdomId">The kingdom context for the operation</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Updated player with produced resources</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="InvalidOperationException">Thrown when production calculation fails</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<Player> ProcessResourceProductionAsync(int playerId, TimeSpan productionDuration, int kingdomId,
+            CancellationToken cancellationToken = default);
+
+        #endregion
+
+        #region VIP System and Monetization
+
+        /// <summary>
+        /// Processes a VIP points purchase for a player, updating VIP level and unlocking benefits.
+        /// Handles VIP level progression, milestone rewards, and secret tier system integration.
+        /// </summary>
+        /// <param name="playerId">The player making the VIP purchase</param>
+        /// <param name="vipPointsPurchased">Number of VIP points purchased</param>
+        /// <param name="kingdomId">The kingdom context for the operation</param>
+        /// <param name="purchaseDetails">Transaction details for purchase logging</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Updated player with new VIP status and rewards</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="InvalidOperationException">Thrown when VIP processing fails</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<Player> ProcessVipPurchaseAsync(int playerId, int vipPointsPurchased, int kingdomId, object purchaseDetails,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Gets players by VIP level range for targeted offers, premium events, and customer service prioritization.
+        /// Supports VIP-specific matchmaking and exclusive content access management.
+        /// </summary>
+        /// <param name="kingdomId">The kingdom to search within</param>
+        /// <param name="minVipLevel">Minimum VIP level (inclusive)</param>
+        /// <param name="maxVipLevel">Maximum VIP level (inclusive)</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Players within the specified VIP level range</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<IEnumerable<Player>> GetPlayersByVipLevelAsync(int kingdomId, int minVipLevel = 0, int maxVipLevel = int.MaxValue,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Claims daily VIP rewards for a player based on their VIP level and login streak.
+        /// Prevents duplicate claims and calculates reward amounts based on VIP benefits.
+        /// </summary>
+        /// <param name="playerId">The player claiming rewards</param>
+        /// <param name="kingdomId">The kingdom context for the operation</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Updated player with claimed rewards and updated claim status</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="InvalidOperationException">Thrown when rewards already claimed or player ineligible</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<Player> ClaimVipDailyRewardsAsync(int playerId, int kingdomId, CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Gets VIP spending analytics for a player including lifetime value, purchase patterns, and chargeback risk.
+        /// Used for customer service, offer personalization, and financial risk management.
+        /// </summary>
+        /// <param name="playerId">The player to analyze</param>
+        /// <param name="kingdomId">The kingdom context for the operation</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Comprehensive VIP spending analytics</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<object> GetPlayerVipAnalyticsAsync(int playerId, int kingdomId, CancellationToken cancellationToken = default);
+
+        #endregion
+
+        #region Teleportation and Movement
+
+        /// <summary>
+        /// Attempts to teleport a player to new coordinates, validating movement rules, proximity restrictions,
+        /// and teleportation costs. Handles free teleports, premium teleports, and alliance territory rules.
+        /// </summary>
+        /// <param name="playerId">The player requesting teleportation</param>
+        /// <param name="targetCoordinates">The desired destination coordinates</param>
+        /// <param name="teleportationType">Free, premium, or alliance-assisted teleport</param>
+        /// <param name="kingdomId">The kingdom context for the operation</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Updated player with new coordinates if successful</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid or teleport violates rules</exception>
+        /// <exception cref="InvalidOperationException">Thrown when player lacks resources or teleport is blocked</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<Player> TeleportPlayerAsync(int playerId, (int X, int Y) targetCoordinates, string teleportationType,
+            int kingdomId, CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Gets players within a specific coordinate radius for local events, alliance recruitment,
+        /// and proximity-based interactions. Supports both circular and square search areas.
+        /// </summary>
+        /// <param name="centerCoordinates">The center point for the search</param>
+        /// <param name="radius">The search radius in coordinate units</param>
+        /// <param name="kingdomId">The kingdom context for the search</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Players within the specified radius</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<IEnumerable<Player>> GetPlayersInRadiusAsync((int X, int Y) centerCoordinates, int radius, int kingdomId,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Updates a player's movement speed modifiers based on research, equipment, and temporary effects.
+        /// Affects march times, teleportation cooldowns, and return speeds.
+        /// </summary>
+        /// <param name="playerId">The player to update</param>
+        /// <param name="speedModifiers">Dictionary of speed modifier sources and values</param>
+        /// <param name="kingdomId">The kingdom context for the operation</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Updated player with new speed calculations</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="InvalidOperationException">Thrown when speed update fails</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<Player> UpdateMovementSpeedAsync(int playerId, Dictionary<string, float> speedModifiers, int kingdomId,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Validates if a teleportation is allowed based on game rules, proximity restrictions, and cooldowns.
+        /// Checks alliance territory rules, enemy proximity blocks, and teleportation history.
+        /// </summary>
+        /// <param name="playerId">The player requesting validation</param>
+        /// <param name="targetCoordinates">The desired destination</param>
+        /// <param name="teleportationType">The type of teleport being attempted</param>
+        /// <param name="kingdomId">The kingdom context for validation</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Validation result with reasons for any restrictions</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<(bool IsAllowed, string[] Restrictions, TimeSpan? Cooldown)> ValidateTeleportationAsync(int playerId,
+            (int X, int Y) targetCoordinates, string teleportationType, int kingdomId, CancellationToken cancellationToken = default);
+
+        #endregion
+
+        #region Research and Technology
+
+        /// <summary>
+        /// Updates a player's research progress in specific technology trees, validating prerequisites
+        /// and resource costs. Handles Military, Economic, and Technology research branches.
+        /// </summary>
+        /// <param name="playerId">The player conducting research</param>
+        /// <param name="researchUpdates">Dictionary of research areas and level increases</param>
+        /// <param name="kingdomId">The kingdom context for the operation</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Updated player with new research levels and unlocked bonuses</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid or research violates prerequisites</exception>
+        /// <exception cref="InvalidOperationException">Thrown when player lacks resources for research</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<Player> UpdateResearchProgressAsync(int playerId, Dictionary<string, int> researchUpdates, int kingdomId,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Gets players by research specialization for alliance coordination and strategic planning.
+        /// Identifies players with advanced military, economic, or technology research for specific roles.
+        /// </summary>
+        /// <param name="kingdomId">The kingdom to search within</param>
+        /// <param name="researchCriteria">Minimum research levels in specific areas</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Players meeting the research criteria</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<IEnumerable<Player>> GetPlayersByResearchSpecializationAsync(int kingdomId, Dictionary<string, int> researchCriteria,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Calculates total research bonuses for a player including base research, alliance research,
+        /// equipment bonuses, and temporary effects. Used for combat calculations and resource production.
+        /// </summary>
+        /// <param name="playerId">The player to calculate bonuses for</param>
+        /// <param name="kingdomId">The kingdom context for the operation</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Comprehensive breakdown of all research bonuses</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<object> CalculateResearchBonusesAsync(int playerId, int kingdomId, CancellationToken cancellationToken = default);
+
+        #endregion
+
+        #region Equipment and Dragon System
+
+        /// <summary>
+        /// Updates a player's equipment loadout, validating equipment compatibility and enhancement levels.
+        /// Handles weapon, armor, and accessory systems with stat bonuses and set effects.
+        /// </summary>
+        /// <param name="playerId">The player updating equipment</param>
+        /// <param name="equipmentChanges">Dictionary of equipment slots and new items</param>
+        /// <param name="kingdomId">The kingdom context for the operation</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Updated player with new equipment and calculated stat bonuses</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid or equipment incompatible</exception>
+        /// <exception cref="InvalidOperationException">Thrown when player lacks required items</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<Player> UpdateEquipmentAsync(int playerId, Dictionary<string, object> equipmentChanges, int kingdomId,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Updates a player's dragon configuration including skill selection, equipment, and evolution progress.
+        /// Dragons must accompany armies and provide skill-based buffs rather than pay-to-win advantages.
+        /// </summary>
+        /// <param name="playerId">The player updating their dragon</param>
+        /// <param name="dragonConfiguration">Dragon skills, equipment, and evolution settings</param>
+        /// <param name="kingdomId">The kingdom context for the operation</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Updated player with new dragon configuration</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid or dragon config is incompatible</exception>
+        /// <exception cref="InvalidOperationException">Thrown when player lacks required dragon resources</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<Player> UpdateDragonConfigurationAsync(int playerId, object dragonConfiguration, int kingdomId,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Gets players by equipment power level for matchmaking, alliance organization, and competitive events.
+        /// Calculates total equipment score including enhancement levels and set bonuses.
+        /// </summary>
+        /// <param name="kingdomId">The kingdom to search within</param>
+        /// <param name="minimumEquipmentPower">Minimum equipment power threshold</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Players meeting the equipment power requirement</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<IEnumerable<Player>> GetPlayersByEquipmentPowerAsync(int kingdomId, long minimumEquipmentPower = 0,
+            CancellationToken cancellationToken = default);
+
+        #endregion
+
+        #region Alliance Integration
+
+        /// <summary>
+        /// Gets all players belonging to a specific alliance within the kingdom for alliance management operations.
+        /// Includes member roles, contribution metrics, and activity status.
+        /// </summary>
+        /// <param name="allianceId">The alliance to get members for</param>
+        /// <param name="kingdomId">The kingdom context for the operation</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>All players who are members of the specified alliance</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<IEnumerable<Player>> GetAllianceMembersAsync(int allianceId, int kingdomId,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Gets players without an alliance within the kingdom for recruitment and alliance invitation systems.
+        /// Filters by activity level, castle level, and availability for alliance participation.
+        /// </summary>
+        /// <param name="kingdomId">The kingdom to search within</param>
+        /// <param name="minimumCastleLevel">Minimum castle level for alliance eligibility</param>
+        /// <param name="activeOnly">Whether to only include recently active players</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Players available for alliance recruitment</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<IEnumerable<Player>> GetPlayersWithoutAllianceAsync(int kingdomId, int minimumCastleLevel = 1,
+            bool activeOnly = true, CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Updates a player's alliance membership, handling alliance changes, role assignments, and contribution tracking.
+        /// Manages leaving previous alliance, cooldown periods, and integration into new alliance systems.
+        /// </summary>
+        /// <param name="playerId">The player changing alliance status</param>
+        /// <param name="newAllianceId">The new alliance ID (null for leaving alliance)</param>
+        /// <param name="membershipRole">The role within the new alliance</param>
+        /// <param name="kingdomId">The kingdom context for the operation</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Updated player with new alliance status</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid or alliance change violates rules</exception>
+        /// <exception cref="InvalidOperationException">Thrown when alliance change fails due to cooldowns or restrictions</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<Player> UpdateAllianceMembershipAsync(int playerId, int? newAllianceId, string? membershipRole, int kingdomId,
+            CancellationToken cancellationToken = default);
+
+        #endregion
+
+        #region Player Analytics and Performance
+
+        /// <summary>
+        /// Gets comprehensive player performance analytics including combat effectiveness, economic efficiency,
+        /// social engagement, and progression metrics for administrative analysis and player development.
+        /// </summary>
+        /// <param name="playerId">The player to analyze</param>
+        /// <param name="kingdomId">The kingdom context for the operation</param>
+        /// <param name="timeRange">The time period to analyze</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Detailed player analytics and performance metrics</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<object> GetPlayerAnalyticsAsync(int playerId, int kingdomId, TimeSpan timeRange,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Gets player leaderboard rankings for various metrics including power, castle level, alliance contribution,
+        /// and KvK performance. Supports multiple ranking categories and time periods.
+        /// </summary>
+        /// <param name="kingdomId">The kingdom to generate rankings for</param>
+        /// <param name="rankingCategory">The metric to rank by (power, level, contribution, etc.)</param>
+        /// <param name="topCount">Number of top players to return</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Top players ranked by the specified metric</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<IEnumerable<(Player Player, object RankingValue, int Rank)>> GetPlayerLeaderboardAsync(int kingdomId,
+            string rankingCategory, int topCount = 100, CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Generates a player development report identifying strengths, weaknesses, and recommended improvement areas.
+        /// Provides personalized guidance for progression optimization and skill development.
+        /// </summary>
+        /// <param name="playerId">The player to generate report for</param>
+        /// <param name="kingdomId">The kingdom context for the operation</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Comprehensive development report with recommendations</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<object> GeneratePlayerDevelopmentReportAsync(int playerId, int kingdomId,
+            CancellationToken cancellationToken = default);
+
+        #endregion
+    }
+}

ShadowedRealmsMobile/src/server/ShadowedRealms.Core/Interfaces/Repositories/IPurchaseLogRepository.cs

@@ -0,0 +1,442 @@
+/*
+ * File: /src/server/ShadowedRealms.Core/Interfaces/Repositories/IPurchaseLogRepository.cs
+ * Created: 2025-10-19
+ * Last Modified: 2025-10-19
+ * Description: Purchase log repository interface defining monetization-specific data access operations.
+ *              Handles transaction tracking, chargeback protection, VIP progression, secret tier system,
+ *              revenue analytics, fraud detection, and customer lifetime value analysis. Critical for
+ *              financial integrity and anti-pay-to-win balance while maintaining sustainable revenue.
+ * Last Edit Notes: Initial implementation with comprehensive monetization tracking, VIP systems, and financial security.
+ */
+
+using ShadowedRealms.Core.Models;
+using ShadowedRealms.Core.Models.Purchase;
+using System.Linq.Expressions;
+
+namespace ShadowedRealms.Core.Interfaces.Repositories
+{
+    /// <summary>
+    /// Repository interface for PurchaseLog entity operations, providing comprehensive monetization management,
+    /// transaction tracking, chargeback protection, VIP progression, and revenue analytics.
+    /// Balances sustainable revenue generation with anti-pay-to-win principles and player value delivery.
+    /// </summary>
+    public interface IPurchaseLogRepository : IRepository<PurchaseLog, int>
+    {
+        #region Transaction Processing and Validation
+
+        /// <summary>
+        /// Records a new purchase transaction with comprehensive validation, fraud detection, and VIP progression.
+        /// Automatically calculates VIP points, milestone rewards, and applies purchase benefits while logging for audit.
+        /// </summary>
+        /// <param name="playerId">The player making the purchase</param>
+        /// <param name="purchaseDetails">Complete purchase information including items, prices, and payment method</param>
+        /// <param name="kingdomId">The kingdom context for the purchase</param>
+        /// <param name="transactionId">External payment processor transaction ID</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Created purchase log with VIP progression and applied benefits</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid or purchase violates policies</exception>
+        /// <exception cref="InvalidOperationException">Thrown when purchase processing fails due to fraud detection</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<PurchaseLog> RecordPurchaseTransactionAsync(int playerId, object purchaseDetails, int kingdomId,
+            string transactionId, CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Validates purchase eligibility based on player status, spending limits, cooldown periods,
+        /// and fraud prevention rules. Prevents exploitation while ensuring legitimate purchases proceed smoothly.
+        /// </summary>
+        /// <param name="playerId">The player attempting the purchase</param>
+        /// <param name="purchaseType">Type of purchase being attempted</param>
+        /// <param name="purchaseAmount">Dollar amount of the purchase</param>
+        /// <param name="kingdomId">The kingdom context for validation</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Purchase eligibility result with restrictions and spending limit information</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<(bool IsEligible, string[] Restrictions, decimal RemainingSpendingLimit, TimeSpan? Cooldown)>
+            ValidatePurchaseEligibilityAsync(int playerId, string purchaseType, decimal purchaseAmount, int kingdomId,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Processes purchase refunds and reversals, handling VIP point adjustments, benefit revocation,
+        /// and account status updates. Maintains financial integrity while supporting customer service.
+        /// </summary>
+        /// <param name="originalPurchaseId">The purchase being refunded</param>
+        /// <param name="refundReason">Reason for refund (customer service, chargeback, etc.)</param>
+        /// <param name="refundAmount">Amount being refunded (can be partial)</param>
+        /// <param name="kingdomId">The kingdom context for the refund</param>
+        /// <param name="authorizingAdminId">Admin authorizing the refund (if applicable)</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Updated purchase log with refund details and account adjustments</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid or refund not allowed</exception>
+        /// <exception cref="InvalidOperationException">Thrown when refund processing fails</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<PurchaseLog> ProcessPurchaseRefundAsync(int originalPurchaseId, string refundReason, decimal refundAmount,
+            int kingdomId, int? authorizingAdminId = null, CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Verifies purchase authenticity with external payment processors to prevent fraud and ensure
+        /// transaction integrity. Cross-references with payment gateway records and validates receipt data.
+        /// </summary>
+        /// <param name="purchaseLogId">The purchase to verify</param>
+        /// <param name="paymentProcessorData">Data from external payment processor for verification</param>
+        /// <param name="kingdomId">The kingdom context for verification</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Verification result with authenticity confirmation and fraud risk assessment</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="InvalidOperationException">Thrown when verification fails or fraud detected</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<(bool IsAuthentic, double FraudRiskScore, string[] VerificationFlags)> VerifyPurchaseAuthenticityAsync(
+            int purchaseLogId, object paymentProcessorData, int kingdomId, CancellationToken cancellationToken = default);
+
+        #endregion
+
+        #region VIP System Integration
+
+        /// <summary>
+        /// Calculates VIP point awards for purchases based on spending amount, purchase type, promotional bonuses,
+        /// and loyalty multipliers. Handles milestone detection and automatic VIP level progression.
+        /// </summary>
+        /// <param name="purchaseAmount">Dollar amount of purchase</param>
+        /// <param name="purchaseType">Type of purchase for bonus calculations</param>
+        /// <param name="playerId">Player for loyalty bonus calculations</param>
+        /// <param name="kingdomId">The kingdom context for calculations</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>VIP point calculation with milestone progression and bonus details</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<(int VipPoints, int NewVipLevel, bool MilestoneReached, object[] UnlockedBenefits)>
+            CalculateVipPointsAsync(decimal purchaseAmount, string purchaseType, int playerId, int kingdomId,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Processes VIP milestone rewards when players reach new VIP levels, including resource packages,
+        /// exclusive items, permanent bonuses, and secret tier system progression tracking.
+        /// </summary>
+        /// <param name="playerId">The player reaching the milestone</param>
+        /// <param name="newVipLevel">The VIP level just achieved</param>
+        /// <param name="triggeringPurchaseId">The purchase that triggered the milestone</param>
+        /// <param name="kingdomId">The kingdom context for reward processing</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Processed milestone rewards with secret tier progression</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid or milestone already claimed</exception>
+        /// <exception cref="InvalidOperationException">Thrown when milestone processing fails</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<object> ProcessVipMilestoneRewardsAsync(int playerId, int newVipLevel, int triggeringPurchaseId,
+            int kingdomId, CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Gets players by VIP spending tier for targeted offers, customer service prioritization,
+        /// and lifetime value analysis. Supports personalized monetization and retention strategies.
+        /// </summary>
+        /// <param name="kingdomId">The kingdom to analyze</param>
+        /// <param name="spendingTier">The spending tier to filter by (whale, dolphin, minnow, F2P)</param>
+        /// <param name="timeframe">Time period for spending calculation</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Players in the specified spending tier with spending analytics</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<IEnumerable<(object PlayerInfo, decimal TotalSpent, string SpendingPattern, double LTV)>>
+            GetPlayersBySpendingTierAsync(int kingdomId, string spendingTier, TimeSpan timeframe,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Tracks secret tier system progression inspired by King of Avalon's hidden VIP benefits.
+        /// Provides additional rewards and recognition for highest-tier spenders without publicizing exact thresholds.
+        /// </summary>
+        /// <param name="playerId">The player to track secret tier progression for</param>
+        /// <param name="purchaseAmount">Recent purchase amount</param>
+        /// <param name="kingdomId">The kingdom context for tracking</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Secret tier progression with unlocked benefits (if any)</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<object> TrackSecretTierProgressionAsync(int playerId, decimal purchaseAmount, int kingdomId,
+            CancellationToken cancellationToken = default);
+
+        #endregion
+
+        #region Chargeback Protection and Fraud Prevention
+
+        /// <summary>
+        /// Processes chargeback notifications from payment processors, automatically adjusting player accounts,
+        /// revoking purchased benefits, and implementing protective measures against future fraud attempts.
+        /// </summary>
+        /// <param name="originalPurchaseId">The purchase being charged back</param>
+        /// <param name="chargebackDetails">Details from payment processor about the chargeback</param>
+        /// <param name="kingdomId">The kingdom context for chargeback processing</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Chargeback processing result with account adjustments and protective measures</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid or purchase not found</exception>
+        /// <exception cref="InvalidOperationException">Thrown when chargeback processing fails</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<object> ProcessChargebackAsync(int originalPurchaseId, object chargebackDetails, int kingdomId,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Identifies high-risk purchase patterns that may indicate fraud, including rapid large purchases,
+        /// unusual payment methods, geographic inconsistencies, and behavioral anomalies for fraud prevention.
+        /// </summary>
+        /// <param name="playerId">The player to analyze for risk patterns</param>
+        /// <param name="recentPurchases">Recent purchase history for pattern analysis</param>
+        /// <param name="kingdomId">The kingdom context for analysis</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Fraud risk assessment with specific risk factors and recommended actions</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<(double RiskScore, string[] RiskFactors, string[] RecommendedActions, bool RequiresReview)>
+            AnalyzeFraudRiskPatternsAsync(int playerId, IEnumerable<object> recentPurchases, int kingdomId,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Implements protective measures for accounts with chargeback history, including purchase restrictions,
+        /// enhanced verification requirements, and monitoring protocols to prevent future losses.
+        /// </summary>
+        /// <param name="playerId">The player to implement protections for</param>
+        /// <param name="protectionLevel">Level of protection based on chargeback severity</param>
+        /// <param name="kingdomId">The kingdom context for protection implementation</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Implemented protection measures with duration and review requirements</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="InvalidOperationException">Thrown when protection implementation fails</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<object> ImplementChargebackProtectionAsync(int playerId, string protectionLevel, int kingdomId,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Gets chargeback analytics for financial risk management including chargeback rates by payment method,
+        /// geographic patterns, player behavior correlations, and financial impact assessment.
+        /// </summary>
+        /// <param name="kingdomId">The kingdom to analyze (null for global analysis)</param>
+        /// <param name="analysisTimeframe">Time period for chargeback analysis</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Comprehensive chargeback analytics with risk mitigation recommendations</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<object> GetChargebackAnalyticsAsync(int? kingdomId, TimeSpan analysisTimeframe,
+            CancellationToken cancellationToken = default);
+
+        #endregion
+
+        #region Revenue Analytics and Optimization
+
+        /// <summary>
+        /// Gets comprehensive revenue analytics including total revenue, average transaction size,
+        /// conversion rates, player lifetime value, and revenue per user metrics for business intelligence.
+        /// </summary>
+        /// <param name="kingdomId">The kingdom to analyze (null for global analysis)</param>
+        /// <param name="analysisTimeframe">Time period for revenue analysis</param>
+        /// <param name="segmentationCriteria">Player segmentation criteria for detailed analysis</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Detailed revenue analytics with trends and optimization recommendations</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<object> GetRevenueAnalyticsAsync(int? kingdomId, TimeSpan analysisTimeframe,
+            object? segmentationCriteria = null, CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Analyzes purchase conversion funnels to identify optimization opportunities including offer timing,
+        /// price points, product bundling effectiveness, and user experience friction points.
+        /// </summary>
+        /// <param name="conversionFunnelType">Type of conversion funnel to analyze</param>
+        /// <param name="kingdomId">The kingdom context for analysis</param>
+        /// <param name="analysisTimeframe">Time period for funnel analysis</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Conversion funnel analysis with optimization recommendations</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<object> AnalyzePurchaseConversionFunnelsAsync(string conversionFunnelType, int kingdomId,
+            TimeSpan analysisTimeframe, CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Gets customer lifetime value predictions based on purchase history, engagement patterns,
+        /// VIP progression, and behavioral indicators for targeted marketing and retention strategies.
+        /// </summary>
+        /// <param name="playerId">The player to calculate LTV for (null for cohort analysis)</param>
+        /// <param name="kingdomId">The kingdom context for calculations</param>
+        /// <param name="predictionHorizon">Time horizon for LTV prediction</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>LTV predictions with confidence intervals and contributing factors</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<object> CalculateCustomerLifetimeValueAsync(int? playerId, int kingdomId, TimeSpan predictionHorizon,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Identifies revenue optimization opportunities including underperforming products, pricing adjustments,
+        /// bundle optimization, and promotional timing for maximizing sustainable revenue growth.
+        /// </summary>
+        /// <param name="optimizationFocus">Area to focus optimization on (pricing, products, timing, etc.)</param>
+        /// <param name="kingdomId">The kingdom context for optimization</param>
+        /// <param name="analysisTimeframe">Time period for optimization analysis</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Revenue optimization recommendations with projected impact</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<object> IdentifyRevenueOptimizationOpportunitiesAsync(string optimizationFocus, int kingdomId,
+            TimeSpan analysisTimeframe, CancellationToken cancellationToken = default);
+
+        #endregion
+
+        #region Player Spending Patterns and Behavior
+
+        /// <summary>
+        /// Gets detailed player spending history including purchase frequency, preferred products, spending triggers,
+        /// and behavioral patterns for personalized offers and customer service optimization.
+        /// </summary>
+        /// <param name="playerId">The player to analyze spending patterns for</param>
+        /// <param name="kingdomId">The kingdom context for analysis</param>
+        /// <param name="analysisTimeframe">Time period for spending pattern analysis</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Comprehensive spending pattern analysis with personalization recommendations</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<object> GetPlayerSpendingPatternsAsync(int playerId, int kingdomId, TimeSpan analysisTimeframe,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Identifies players at risk of churn based on spending pattern changes, engagement decline,
+        /// and behavioral indicators for targeted retention campaigns and personalized re-engagement.
+        /// </summary>
+        /// <param name="kingdomId">The kingdom to analyze for churn risk</param>
+        /// <param name="riskThreshold">Risk threshold for churn prediction</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Players at risk of churn with risk factors and retention recommendations</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<IEnumerable<(object PlayerInfo, double ChurnRisk, string[] RiskFactors, object[] RetentionActions)>>
+            IdentifyPlayersAtChurnRiskAsync(int kingdomId, double riskThreshold = 0.7,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Analyzes spending triggers and motivations to understand what drives purchase decisions,
+        /// including competitive pressure, progression needs, social factors, and event participation.
+        /// </summary>
+        /// <param name="purchaseLogIds">Specific purchases to analyze triggers for</param>
+        /// <param name="kingdomId">The kingdom context for analysis</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Spending trigger analysis with motivation insights and optimization opportunities</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<object> AnalyzeSpendingTriggersAsync(IEnumerable<int> purchaseLogIds, int kingdomId,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Gets cohort analysis of player spending behavior over time, tracking how spending patterns
+        /// evolve based on registration date, first purchase timing, and progression milestones.
+        /// </summary>
+        /// <param name="cohortDefinition">How to define cohorts (registration month, first purchase, etc.)</param>
+        /// <param name="kingdomId">The kingdom context for cohort analysis</param>
+        /// <param name="analysisTimeframe">Time period for cohort tracking</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Cohort spending analysis with lifecycle insights and optimization recommendations</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<object> GetSpendingCohortAnalysisAsync(string cohortDefinition, int kingdomId, TimeSpan analysisTimeframe,
+            CancellationToken cancellationToken = default);
+
+        #endregion
+
+        #region Anti-Pay-to-Win Balance Monitoring
+
+        /// <summary>
+        /// Monitors purchase impact on game balance to ensure spending provides value without creating
+        /// pay-to-win dominance. Tracks competitive balance metrics and player satisfaction indicators.
+        /// </summary>
+        /// <param name="kingdomId">The kingdom to monitor balance for</param>
+        /// <param name="monitoringTimeframe">Time period for balance monitoring</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Game balance analysis with pay-to-win risk assessment and adjustment recommendations</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<object> MonitorPurchaseImpactOnGameBalanceAsync(int kingdomId, TimeSpan monitoringTimeframe,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Analyzes effectiveness of skill-based alternatives to premium features, ensuring free-to-play
+        /// players can achieve competitive results through skill and time investment rather than spending.
+        /// </summary>
+        /// <param name="skillBasedFeature">The skill-based alternative to analyze</param>
+        /// <param name="kingdomId">The kingdom context for analysis</param>
+        /// <param name="analysisTimeframe">Time period for effectiveness analysis</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Skill-based alternative effectiveness with balance recommendations</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<object> AnalyzeSkillBasedAlternativeEffectivenessAsync(string skillBasedFeature, int kingdomId,
+            TimeSpan analysisTimeframe, CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Gets competitive balance metrics comparing performance of paying vs non-paying players
+        /// to ensure spending enhances experience without creating unfair advantages or dominance.
+        /// </summary>
+        /// <param name="kingdomId">The kingdom to analyze competitive balance for</param>
+        /// <param name="competitiveMetric">The metric to analyze (power, progression, success rate, etc.)</param>
+        /// <param name="analysisTimeframe">Time period for competitive analysis</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Competitive balance analysis with fairness assessment and adjustment recommendations</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<object> GetCompetitiveBalanceMetricsAsync(int kingdomId, string competitiveMetric,
+            TimeSpan analysisTimeframe, CancellationToken cancellationToken = default);
+
+        #endregion
+
+        #region Purchase History and Audit Trails
+
+        /// <summary>
+        /// Gets comprehensive purchase history for a player including all transactions, refunds, chargebacks,
+        /// VIP progression, and account adjustments for customer service and audit purposes.
+        /// </summary>
+        /// <param name="playerId">The player to get purchase history for</param>
+        /// <param name="kingdomId">The kingdom context for the history</param>
+        /// <param name="includeRefunds">Whether to include refunded transactions</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Complete purchase history with transaction details and account impacts</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<IEnumerable<object>> GetPlayerPurchaseHistoryAsync(int playerId, int kingdomId, bool includeRefunds = true,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Gets purchase audit trail for financial compliance and investigation purposes including
+        /// all transaction modifications, admin actions, system adjustments, and verification records.
+        /// </summary>
+        /// <param name="purchaseLogId">The purchase to get audit trail for</param>
+        /// <param name="kingdomId">The kingdom context for the audit</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Complete audit trail with chronological record of all purchase-related actions</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<object> GetPurchaseAuditTrailAsync(int purchaseLogId, int kingdomId,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Generates financial compliance reports for regulatory requirements, tax reporting,
+        /// and internal audit purposes including revenue reconciliation and transaction verification.
+        /// </summary>
+        /// <param name="reportType">Type of compliance report to generate</param>
+        /// <param name="reportingPeriod">Time period for the compliance report</param>
+        /// <param name="jurisdictionRequirements">Specific regulatory requirements to address</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Compliance report with required financial data and verification</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<object> GenerateComplianceReportAsync(string reportType, TimeSpan reportingPeriod,
+            object? jurisdictionRequirements = null, CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Validates purchase data integrity by cross-referencing internal records with external payment
+        /// processor data, identifying discrepancies, and ensuring financial accuracy for audit purposes.
+        /// </summary>
+        /// <param name="validationTimeframe">Time period to validate purchase data for</param>
+        /// <param name="paymentProcessorRecords">External records for cross-reference</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Data integrity validation results with discrepancy identification and resolution</returns>
+        /// <exception cref="ArgumentException">Thrown when parameters are invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<object> ValidatePurchaseDataIntegrityAsync(TimeSpan validationTimeframe,
+            object? paymentProcessorRecords = null, CancellationToken cancellationToken = default);
+
+        #endregion
+    }
+}

ShadowedRealmsMobile/src/server/ShadowedRealms.Core/Interfaces/Repositories/IRepository.cs

@@ -0,0 +1,336 @@
+/*
+ * File: /src/server/ShadowedRealms.Core/Interfaces/Repositories/IRepository.cs
+ * Created: 2025-10-19
+ * Last Modified: 2025-10-19
+ * Description: Base repository interface defining common CRUD operations with kingdom-scoped data access patterns.
+ *              All specific repository interfaces inherit from this to ensure consistent data access patterns
+ *              and kingdom boundary enforcement across the entire application.
+ * Last Edit Notes: Initial implementation with comprehensive async operations, kingdom scoping, and error handling contracts.
+ */
+
+using System.Linq.Expressions;
+
+namespace ShadowedRealms.Core.Interfaces.Repositories
+{
+    /// <summary>
+    /// Base repository interface providing common CRUD operations with kingdom-scoped data access.
+    /// All entity repositories must inherit from this interface to ensure consistent data access patterns
+    /// and automatic kingdom boundary enforcement.
+    /// </summary>
+    /// <typeparam name="TEntity">The entity type that this repository manages</typeparam>
+    /// <typeparam name="TKey">The primary key type for the entity</typeparam>
+    public interface IRepository<TEntity, TKey> where TEntity : class
+    {
+        #region Kingdom-Scoped Query Operations
+
+        /// <summary>
+        /// Gets an entity by its primary key within the specified kingdom context.
+        /// Automatically applies kingdom-scoped filtering to prevent cross-kingdom data access.
+        /// </summary>
+        /// <param name="id">The primary key of the entity to retrieve</param>
+        /// <param name="kingdomId">The kingdom context for the query</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>The entity if found within the kingdom, null otherwise</returns>
+        /// <exception cref="ArgumentException">Thrown when kingdomId is invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<TEntity?> GetByIdAsync(TKey id, int kingdomId, CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Gets an entity by its primary key with related entities included, within the specified kingdom context.
+        /// Automatically applies kingdom-scoped filtering to all included navigation properties.
+        /// </summary>
+        /// <param name="id">The primary key of the entity to retrieve</param>
+        /// <param name="kingdomId">The kingdom context for the query</param>
+        /// <param name="includeProperties">Navigation properties to include in the query</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>The entity with included properties if found within the kingdom, null otherwise</returns>
+        /// <exception cref="ArgumentException">Thrown when kingdomId is invalid or includeProperties contains invalid property names</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<TEntity?> GetByIdWithIncludesAsync(TKey id, int kingdomId, CancellationToken cancellationToken = default,
+            params Expression<Func<TEntity, object>>[] includeProperties);
+
+        /// <summary>
+        /// Gets all entities within the specified kingdom context.
+        /// Results are automatically filtered to prevent cross-kingdom data access.
+        /// </summary>
+        /// <param name="kingdomId">The kingdom context for the query</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>All entities belonging to the specified kingdom</returns>
+        /// <exception cref="ArgumentException">Thrown when kingdomId is invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<IEnumerable<TEntity>> GetAllAsync(int kingdomId, CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Gets entities matching the specified predicate within the kingdom context.
+        /// The predicate is combined with kingdom-scoped filtering automatically.
+        /// </summary>
+        /// <param name="predicate">The condition to filter entities</param>
+        /// <param name="kingdomId">The kingdom context for the query</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Entities matching the predicate within the specified kingdom</returns>
+        /// <exception cref="ArgumentNullException">Thrown when predicate is null</exception>
+        /// <exception cref="ArgumentException">Thrown when kingdomId is invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<IEnumerable<TEntity>> GetWhereAsync(Expression<Func<TEntity, bool>> predicate, int kingdomId,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Gets entities matching the specified predicate with related entities included, within the kingdom context.
+        /// Both the predicate and includes are automatically kingdom-scoped.
+        /// </summary>
+        /// <param name="predicate">The condition to filter entities</param>
+        /// <param name="kingdomId">The kingdom context for the query</param>
+        /// <param name="includeProperties">Navigation properties to include in the query</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Entities matching the predicate with included properties within the specified kingdom</returns>
+        /// <exception cref="ArgumentNullException">Thrown when predicate is null</exception>
+        /// <exception cref="ArgumentException">Thrown when kingdomId is invalid or includeProperties contains invalid property names</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<IEnumerable<TEntity>> GetWhereWithIncludesAsync(Expression<Func<TEntity, bool>> predicate, int kingdomId,
+            CancellationToken cancellationToken = default, params Expression<Func<TEntity, object>>[] includeProperties);
+
+        /// <summary>
+        /// Gets the first entity matching the specified predicate within the kingdom context, or null if not found.
+        /// Automatically applies kingdom-scoped filtering.
+        /// </summary>
+        /// <param name="predicate">The condition to filter entities</param>
+        /// <param name="kingdomId">The kingdom context for the query</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>The first matching entity within the kingdom, or null if not found</returns>
+        /// <exception cref="ArgumentNullException">Thrown when predicate is null</exception>
+        /// <exception cref="ArgumentException">Thrown when kingdomId is invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<TEntity?> GetFirstOrDefaultAsync(Expression<Func<TEntity, bool>> predicate, int kingdomId,
+            CancellationToken cancellationToken = default);
+
+        #endregion
+
+        #region Paginated Query Operations
+
+        /// <summary>
+        /// Gets a paginated list of entities within the specified kingdom context.
+        /// Results are automatically kingdom-scoped and ordered for consistent pagination.
+        /// </summary>
+        /// <param name="pageNumber">The page number (1-based)</param>
+        /// <param name="pageSize">The number of entities per page</param>
+        /// <param name="kingdomId">The kingdom context for the query</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Paginated results within the specified kingdom</returns>
+        /// <exception cref="ArgumentException">Thrown when pageNumber or pageSize is invalid, or kingdomId is invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<(IEnumerable<TEntity> Items, int TotalCount, int PageCount)> GetPagedAsync(int pageNumber, int pageSize,
+            int kingdomId, CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Gets a paginated list of entities matching the specified predicate within the kingdom context.
+        /// Results are automatically kingdom-scoped and ordered for consistent pagination.
+        /// </summary>
+        /// <param name="predicate">The condition to filter entities</param>
+        /// <param name="pageNumber">The page number (1-based)</param>
+        /// <param name="pageSize">The number of entities per page</param>
+        /// <param name="kingdomId">The kingdom context for the query</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Paginated filtered results within the specified kingdom</returns>
+        /// <exception cref="ArgumentNullException">Thrown when predicate is null</exception>
+        /// <exception cref="ArgumentException">Thrown when pageNumber or pageSize is invalid, or kingdomId is invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<(IEnumerable<TEntity> Items, int TotalCount, int PageCount)> GetPagedWhereAsync(
+            Expression<Func<TEntity, bool>> predicate, int pageNumber, int pageSize, int kingdomId,
+            CancellationToken cancellationToken = default);
+
+        #endregion
+
+        #region Count and Existence Operations
+
+        /// <summary>
+        /// Gets the count of all entities within the specified kingdom context.
+        /// Automatically applies kingdom-scoped filtering.
+        /// </summary>
+        /// <param name="kingdomId">The kingdom context for the query</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>The count of entities within the specified kingdom</returns>
+        /// <exception cref="ArgumentException">Thrown when kingdomId is invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<int> CountAsync(int kingdomId, CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Gets the count of entities matching the specified predicate within the kingdom context.
+        /// The predicate is combined with kingdom-scoped filtering automatically.
+        /// </summary>
+        /// <param name="predicate">The condition to filter entities</param>
+        /// <param name="kingdomId">The kingdom context for the query</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>The count of matching entities within the specified kingdom</returns>
+        /// <exception cref="ArgumentNullException">Thrown when predicate is null</exception>
+        /// <exception cref="ArgumentException">Thrown when kingdomId is invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<int> CountWhereAsync(Expression<Func<TEntity, bool>> predicate, int kingdomId,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Checks if any entity exists within the specified kingdom context.
+        /// Automatically applies kingdom-scoped filtering.
+        /// </summary>
+        /// <param name="kingdomId">The kingdom context for the query</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>True if any entities exist within the kingdom, false otherwise</returns>
+        /// <exception cref="ArgumentException">Thrown when kingdomId is invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<bool> AnyAsync(int kingdomId, CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Checks if any entity matching the specified predicate exists within the kingdom context.
+        /// The predicate is combined with kingdom-scoped filtering automatically.
+        /// </summary>
+        /// <param name="predicate">The condition to filter entities</param>
+        /// <param name="kingdomId">The kingdom context for the query</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>True if any matching entities exist within the kingdom, false otherwise</returns>
+        /// <exception cref="ArgumentNullException">Thrown when predicate is null</exception>
+        /// <exception cref="ArgumentException">Thrown when kingdomId is invalid</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<bool> AnyAsync(Expression<Func<TEntity, bool>> predicate, int kingdomId,
+            CancellationToken cancellationToken = default);
+
+        #endregion
+
+        #region Modification Operations
+
+        /// <summary>
+        /// Adds a new entity to the repository within the specified kingdom context.
+        /// The entity's kingdom association is automatically validated and enforced.
+        /// </summary>
+        /// <param name="entity">The entity to add</param>
+        /// <param name="kingdomId">The kingdom context for the operation</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>The added entity with any generated values populated</returns>
+        /// <exception cref="ArgumentNullException">Thrown when entity is null</exception>
+        /// <exception cref="ArgumentException">Thrown when kingdomId is invalid or entity belongs to different kingdom</exception>
+        /// <exception cref="InvalidOperationException">Thrown when entity violates business rules</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<TEntity> AddAsync(TEntity entity, int kingdomId, CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Adds multiple entities to the repository within the specified kingdom context.
+        /// All entities' kingdom associations are automatically validated and enforced.
+        /// </summary>
+        /// <param name="entities">The entities to add</param>
+        /// <param name="kingdomId">The kingdom context for the operation</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>The added entities with any generated values populated</returns>
+        /// <exception cref="ArgumentNullException">Thrown when entities collection is null</exception>
+        /// <exception cref="ArgumentException">Thrown when kingdomId is invalid or any entity belongs to different kingdom</exception>
+        /// <exception cref="InvalidOperationException">Thrown when any entity violates business rules</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<IEnumerable<TEntity>> AddRangeAsync(IEnumerable<TEntity> entities, int kingdomId,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Updates an existing entity within the specified kingdom context.
+        /// The entity's kingdom association is validated to prevent cross-kingdom modifications.
+        /// </summary>
+        /// <param name="entity">The entity to update</param>
+        /// <param name="kingdomId">The kingdom context for the operation</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>The updated entity</returns>
+        /// <exception cref="ArgumentNullException">Thrown when entity is null</exception>
+        /// <exception cref="ArgumentException">Thrown when kingdomId is invalid or entity belongs to different kingdom</exception>
+        /// <exception cref="InvalidOperationException">Thrown when entity doesn't exist or violates business rules</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<TEntity> UpdateAsync(TEntity entity, int kingdomId, CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Updates multiple entities within the specified kingdom context.
+        /// All entities' kingdom associations are validated to prevent cross-kingdom modifications.
+        /// </summary>
+        /// <param name="entities">The entities to update</param>
+        /// <param name="kingdomId">The kingdom context for the operation</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>The updated entities</returns>
+        /// <exception cref="ArgumentNullException">Thrown when entities collection is null</exception>
+        /// <exception cref="ArgumentException">Thrown when kingdomId is invalid or any entity belongs to different kingdom</exception>
+        /// <exception cref="InvalidOperationException">Thrown when any entity doesn't exist or violates business rules</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<IEnumerable<TEntity>> UpdateRangeAsync(IEnumerable<TEntity> entities, int kingdomId,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Deletes an entity by its primary key within the specified kingdom context.
+        /// Automatically validates kingdom association before deletion.
+        /// </summary>
+        /// <param name="id">The primary key of the entity to delete</param>
+        /// <param name="kingdomId">The kingdom context for the operation</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>True if the entity was deleted, false if not found</returns>
+        /// <exception cref="ArgumentException">Thrown when kingdomId is invalid</exception>
+        /// <exception cref="InvalidOperationException">Thrown when entity cannot be deleted due to business rules</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<bool> DeleteAsync(TKey id, int kingdomId, CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Deletes an entity within the specified kingdom context.
+        /// Automatically validates kingdom association before deletion.
+        /// </summary>
+        /// <param name="entity">The entity to delete</param>
+        /// <param name="kingdomId">The kingdom context for the operation</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>True if the entity was deleted, false if not found</returns>
+        /// <exception cref="ArgumentNullException">Thrown when entity is null</exception>
+        /// <exception cref="ArgumentException">Thrown when kingdomId is invalid or entity belongs to different kingdom</exception>
+        /// <exception cref="InvalidOperationException">Thrown when entity cannot be deleted due to business rules</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<bool> DeleteAsync(TEntity entity, int kingdomId, CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Deletes entities matching the specified predicate within the kingdom context.
+        /// The predicate is combined with kingdom-scoped filtering automatically.
+        /// </summary>
+        /// <param name="predicate">The condition to filter entities for deletion</param>
+        /// <param name="kingdomId">The kingdom context for the operation</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>The number of entities deleted</returns>
+        /// <exception cref="ArgumentNullException">Thrown when predicate is null</exception>
+        /// <exception cref="ArgumentException">Thrown when kingdomId is invalid</exception>
+        /// <exception cref="InvalidOperationException">Thrown when entities cannot be deleted due to business rules</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<int> DeleteWhereAsync(Expression<Func<TEntity, bool>> predicate, int kingdomId,
+            CancellationToken cancellationToken = default);
+
+        #endregion
+
+        #region Transaction and Performance Operations
+
+        /// <summary>
+        /// Executes a database operation within a transaction scope, automatically handling rollback on exceptions.
+        /// All operations within the transaction maintain kingdom-scoped security.
+        /// </summary>
+        /// <typeparam name="TResult">The return type of the operation</typeparam>
+        /// <param name="operation">The operation to execute within the transaction</param>
+        /// <param name="kingdomId">The kingdom context for the transaction</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>The result of the operation</returns>
+        /// <exception cref="ArgumentNullException">Thrown when operation is null</exception>
+        /// <exception cref="ArgumentException">Thrown when kingdomId is invalid</exception>
+        /// <exception cref="InvalidOperationException">Thrown when transaction fails</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<TResult> ExecuteInTransactionAsync<TResult>(Func<Task<TResult>> operation, int kingdomId,
+            CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Executes a raw SQL query with parameters, automatically applying kingdom-scoped filtering.
+        /// Use only when LINQ queries are insufficient for performance or complexity requirements.
+        /// </summary>
+        /// <param name="sql">The SQL query with parameter placeholders</param>
+        /// <param name="kingdomId">The kingdom context for the query</param>
+        /// <param name="parameters">The parameters for the SQL query</param>
+        /// <param name="cancellationToken">Cancellation token for async operation</param>
+        /// <returns>Entities returned by the SQL query within the kingdom context</returns>
+        /// <exception cref="ArgumentException">Thrown when sql is null/empty or kingdomId is invalid</exception>
+        /// <exception cref="InvalidOperationException">Thrown when SQL execution fails</exception>
+        /// <exception cref="OperationCanceledException">Thrown when operation is cancelled</exception>
+        Task<IEnumerable<TEntity>> ExecuteRawSqlAsync(string sql, int kingdomId,
+            CancellationToken cancellationToken = default, params object[] parameters);
+
+        #endregion
+    }
+}