fix: Use reference equality for transaction sharing detection

PROBLEM:
--------
The original CanShareTransaction() implementation used CONNECTION STRING comparison
to determine if contexts could share transactions. This was fundamentally incorrect
because EF Core's UseTransaction() requires the SAME DbConnection OBJECT INSTANCE
(reference equality), not just matching connection strings.

Each call to .UseSqlServer(connectionString) creates a NEW DbConnection object, so:
- Two contexts with identical connection strings had DIFFERENT connection objects
- String comparison returned TRUE (same strings)
- UseTransaction() would fail or behave unpredictably (different objects)

WHY THIS MATTERS:
-----------------
EF Core's UseTransaction(DbTransaction) method requires that the DbTransaction be
associated with the SAME physical DbConnection that all contexts use. Reference
equality is required - the database cannot coordinate transactions across separate
connection objects even if they connect to the same database.

SOLUTION:
---------
1. Changed CanShareTransaction() from string comparison to reference equality check:
   OLD: return connection?.ConnectionString == firstConnectionString;
   NEW: return ReferenceEquals(connection, firstConnection);

2. Updated ALL documentation to show correct pattern:
   - Users MUST create ONE DbConnection object
   - Pass SAME connection instance to all contexts
   - Connection lifetime is user's responsibility

3. Added XML documentation explaining reference equality requirement

4. Updated context factory pattern to store and reuse connection object

5. Added connection lifetime management guidance

IMPACT:
-------
This is a design correction made BEFORE PR casbin-net#85 merges to upstream, so there is
NO breaking change to released code. The PR documentation and implementation are
being corrected to reflect EF Core's actual requirements.

Users following the corrected pattern will get reliable atomic transactions.
Users who need separate databases will get predictable non-atomic behavior.

FILES CHANGED:
--------------
- EFCoreAdapter.cs: CanShareTransaction() now uses ReferenceEquals()
- MULTI_CONTEXT_USAGE_GUIDE.md: All examples show shared connection object pattern
- MULTI_CONTEXT_DESIGN.md: Detection logic updated to explain reference equality

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: thoraj

Casbin.Persist.Adapter.EFCore/EFCoreAdapter.cs

@@ -258,27 +258,36 @@ private void SavePolicyWithIndividualTransactions(IPolicyStore store, List<DbCon
             }
         }
 
+        /// <summary>
+        /// Determines if contexts can share a transaction by checking if they use the same physical DbConnection instance.
+        /// </summary>
+        /// <remarks>
+        /// EF Core's UseTransaction() requires that all contexts use the SAME DbConnection object instance
+        /// (reference equality), not just identical connection strings. Users must explicitly create contexts
+        /// with a shared DbConnection object for transaction coordination to work.
+        /// </remarks>
+        /// <param name="contexts">List of contexts to check for shared connection</param>
+        /// <returns>True if all contexts share the same DbConnection instance; otherwise false</returns>
         private bool CanShareTransaction(List<DbContext> contexts)
         {
-            // Check if all contexts share the same connection string
-            // For SQLite, separate database files cannot share transactions
+            // Check if all contexts share the same physical DbConnection object
+            // EF Core's UseTransaction() requires reference equality, not string equality
             if (contexts.Count <= 1) return true;
 
             try
             {
                 var firstConnection = contexts[0].Database.GetDbConnection();
-                var firstConnectionString = firstConnection?.ConnectionString;
 
-                if (string.IsNullOrEmpty(firstConnectionString))
+                if (firstConnection == null)
                 {
-                    // If we can't determine connection strings, assume separate connections
                     return false;
                 }
 
+                // Check reference equality - contexts must share the SAME connection object
                 return contexts.All(c =>
                 {
                     var connection = c.Database.GetDbConnection();
-                    return connection?.ConnectionString == firstConnectionString;
+                    return ReferenceEquals(connection, firstConnection);
                 });
             }
             catch (Exception)

MULTI_CONTEXT_DESIGN.md

@@ -134,15 +134,15 @@ private bool CanShareTransaction(List<DbContext> contexts)
     try
     {
         var firstConnection = contexts[0].Database.GetDbConnection();
-        var firstConnectionString = firstConnection?.ConnectionString;
 
-        if (string.IsNullOrEmpty(firstConnectionString))
+        if (firstConnection == null)
             return false;
 
+        // Check reference equality - contexts must share the SAME connection object
         return contexts.All(c =>
         {
             var connection = c.Database.GetDbConnection();
-            return connection?.ConnectionString == firstConnectionString;
+            return ReferenceEquals(connection, firstConnection);
         });
     }
     catch (Exception)
@@ -155,14 +155,15 @@ private bool CanShareTransaction(List<DbContext> contexts)
 ```
 
 **Detection Strategy:**
-- Compare connection strings across all contexts
-- If all match → use shared transaction (atomic)
-- If any differ → use individual transactions (not atomic)
+- Check if all contexts share the **same DbConnection object** (reference equality)
+- EF Core's `UseTransaction()` requires the same physical connection instance
+- If all contexts use same DbConnection → use shared transaction (atomic)
+- If any context uses different DbConnection → use individual transactions (not atomic)
 - No errors thrown → graceful degradation
 
 #### Shared Transaction Pattern
 
-When connection strings match:
+When contexts share the same DbConnection object:
 
 ```csharp
 // Pseudocode
@@ -183,7 +184,7 @@ transaction.Commit(); // Atomic across all contexts
 
 #### Individual Transaction Pattern
 
-When connection strings differ (e.g., separate SQLite files):
+When contexts use different DbConnection objects:
 
 ```csharp
 // Pseudocode - WARNING: Not atomic across contexts
@@ -214,8 +215,8 @@ foreach (var context in contexts)
 | **SQLite** | ✅ | N/A | ✅ (same file) | ⚠️ (no atomicity) | ✅ (same file only) |
 
 **Key Constraints:**
-- All contexts must connect to the same database for shared transactions
-- SQLite cannot share transactions across different files
+- All contexts must use the **same DbConnection object instance** for shared transactions
+- Users must explicitly create and pass a shared connection object to all contexts
 - Distributed transactions (cross-database) are not supported
 
 ## Implementation Details