v2.5.11: replace CosmoKvConnection._lock with Microsoft.VisualStudio.

Threading.AsyncReaderWriterLock

The single SemaphoreSlim(1,1) on CosmoKvConnection has been the gating
bottleneck behind every transport optimisation this session — UDS,
binary protocol, client connection pool all invisible against it
because the server-side serialised everything anyway. Two prior v2.5.7
attempts at rolling our own RW lock failed: drain-N-slots starved
writers under sustained read load, writer-priority gate hit subtle
timing races under xUnit parallelism. The Microsoft.VisualStudio.
Threading.AsyncReaderWriterLock is the same primitive Visual Studio's
project-model uses; bounded fairness + cooperative cancellation
already correct.

Wiring:
  - QueryAsync               → ReadLockAsync (concurrent)
  - ExecuteAsync             → WriteLockAsync (exclusive)
  - BeginTransactionAsync    → WriteLockAsync
  - CommitAsync              → WriteLockAsync
  - RollbackAsync            → WriteLockAsync

The Executor-side AsyncLocal<IKvAccess?> from v2.5.8 stays in place —
it's the necessary per-call isolation for concurrent reads on the
shared executor. The ConcurrentDictionary<,> swap for the parser
cache stays too.

3 new xUnit tests in Phase30AsyncRWLockTests verify:
  1. 32 concurrent SELECTs measurably faster than serial (<70% of
     serial time) — the observable that proves the read lock is
     non-exclusive.
  2. Reader observing COUNT(*) during concurrent INSERTs never sees
     count decrease — write/read isolation.
  3. Writer not starved under 8 hot reader tasks — the v2.5.7
     drain-N attempt hung this test indefinitely.

All 269 CosmoKv driver tests pass (was 266; +3 new). Pipes pool
tests still 10/10. Once this lands on marivil, the binary-protocol +
pool work from v2.5.10 should finally become a measurable win — the
client-side parallelism now actually maps to server-side parallel
execution.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: vkuttyp

Directory.Build.props

@@ -7,6 +7,6 @@
     <Authors>vkuttyp</Authors>
     <PackageLicenseExpression>MIT</PackageLicenseExpression>
     <RepositoryUrl>https://github.com/vkuttyp/CosmoSQLClient-Dotnet</RepositoryUrl>
-    <Version>2.5.10</Version>
+    <Version>2.5.11</Version>
   </PropertyGroup>
 </Project>

src/CosmoSQLClient.CosmoKv/CosmoKvConnection.cs

@@ -36,18 +36,22 @@ public sealed class CosmoKvConnection : ISqlDatabase
     private CosmoKvTxn? _txn;
 
     /// <summary>
-    /// Connection-level serialisation lock. The v2.5.7 attempt at an
-    /// AsyncReaderWriterLock here regressed marivil's stress run badly —
-    /// the "drain N slots" writer pattern starved under sustained read
-    /// load (audit/RelayWorker writes blocked indefinitely), and a
-    /// "writer-priority gate" rewrite hit subtler timing issues under
-    /// the .NET test suite's parallel-test load. Reverted to the single
-    /// SemaphoreSlim until a properly-engineered async RW lock can be
-    /// designed; the <see cref="Execution.Executor"/>-side AsyncLocal
-    /// change stays (it's harmless under serial access and enables the
-    /// eventual RW-lock work without another driver-side refactor).
+    /// Battle-tested writer-priority RW lock from Microsoft.VisualStudio.
+    /// Threading. Multiple readers run concurrently (snapshot-isolated via
+    /// MVCC); ExecuteAsync / Begin / Commit / Rollback acquire the write
+    /// lock for exclusive access. Pre-v2.5.11 was a single SemaphoreSlim
+    /// (everything serial), which was the gating bottleneck behind every
+    /// transport optimisation this session (UDS, binary protocol, client
+    /// pool — all invisible against this lock).
+    ///
+    /// Two prior v2.5.7 attempts at rolling our own RW lock failed —
+    /// the drain-N-slots writer pattern starved under sustained read
+    /// load and a writer-priority gate rewrite hit subtle timing issues
+    /// under xUnit's parallel harness. The MS lock primitive handles
+    /// both correctly (it's the same one Visual Studio's project system
+    /// uses for cross-thread project model access).
     /// </summary>
-    private readonly SemaphoreSlim _lock = new(1, 1);
+    private readonly Microsoft.VisualStudio.Threading.AsyncReaderWriterLock _rwLock = new();
     private bool _disposed;
 
     /// <summary>
@@ -185,28 +189,29 @@ public static Task<CosmoKvConnection> OpenAsync(
     public async Task<IReadOnlyList<SqlRow>> QueryAsync(
         string sql, IReadOnlyList<SqlParameter>? parameters = null, CancellationToken ct = default)
     {
-        await _lock.WaitAsync(ct);
-        try
+        using (await _rwLock.ReadLockAsync(ct))
         {
             EnsureOpen();
             var stmt = TSqlParser.Parse(sql);
             // Snapshot _txn under the read lock so a concurrent BEGIN
-            // (which holds the write lock and excludes us) can't change
-            // our view mid-execution. Once snapshotted, the per-call
-            // access lives in the Executor's AsyncLocal slot, so
-            // sibling readers don't see our routing.
+            // (which would hold the write lock and exclude us) can't
+            // change our view mid-execution. The per-call access lives
+            // in the Executor's AsyncLocal slot, so sibling readers
+            // don't see our routing.
             var snapshotTxn = _txn;
-            if (snapshotTxn is not null)
-                _executor!.SetActiveAccess(new TxnKvAccess(snapshotTxn));
-            else
-                _executor!.SetActiveAccess(null);
-            var (cols, rows) = await _executor!.QueryAsync(stmt, parameters, ct);
-            return MaterializeRows(cols, rows);
-        }
-        finally
-        {
-            _executor?.SetActiveAccess(null);
-            _lock.Release();
+            try
+            {
+                if (snapshotTxn is not null)
+                    _executor!.SetActiveAccess(new TxnKvAccess(snapshotTxn));
+                else
+                    _executor!.SetActiveAccess(null);
+                var (cols, rows) = await _executor!.QueryAsync(stmt, parameters, ct);
+                return MaterializeRows(cols, rows);
+            }
+            finally
+            {
+                _executor?.SetActiveAccess(null);
+            }
         }
     }
 
@@ -234,60 +239,61 @@ public async IAsyncEnumerable<SqlRow> QueryStreamAsync(
     public async Task<int> ExecuteAsync(
         string sql, IReadOnlyList<SqlParameter>? parameters = null, CancellationToken ct = default)
     {
-        await _lock.WaitAsync(ct);
-        try
+        using (await _rwLock.WriteLockAsync(ct))
         {
-            EnsureOpen();
-            var stmt = TSqlParser.Parse(sql);
-
-            // SQL-level transaction commands — intercept before the executor.
-            switch (stmt)
-            {
-                case BeginTransactionStatement:
-                    await BeginTransactionAsyncLocked(ct);
-                    return 0;
-                case CommitTransactionStatement:
-                    await CommitAsyncLocked(ct);
-                    return 0;
-                case RollbackTransactionStatement:
-                    await RollbackAsyncLocked(ct);
-                    return 0;
-            }
-
-            if (_txn is not null)
-            {
-                // Inside an explicit transaction — buffer into it.
-                _executor!.SetActiveAccess(new TxnKvAccess(_txn));
-                return await _executor!.ExecuteAsync(stmt, parameters, ct);
-            }
-
-            // Implicit per-statement transaction so multi-key writes (row +
-            // index entries + IDENTITY counter) are atomic. CosmoKv's writer
-            // batches the buffer into one append, so the cost of the wrap
-            // is small.
-            var t = _db!.BeginTransaction(update: true);
             try
             {
-                _executor!.SetActiveAccess(new TxnKvAccess(t));
-                int n = await _executor!.ExecuteAsync(stmt, parameters, ct);
-                await t.CommitAsync(ct);
-                return n;
-            }
-            catch (global::CosmoKv.ConflictException ce)
-            {
-                throw new SqlTransactionConflictException(
-                    "Implicit transaction failed due to a concurrent write conflict.", ce);
+                EnsureOpen();
+                var stmt = TSqlParser.Parse(sql);
+
+                // SQL-level transaction commands — intercept before the executor.
+                switch (stmt)
+                {
+                    case BeginTransactionStatement:
+                        await BeginTransactionAsyncLocked(ct);
+                        return 0;
+                    case CommitTransactionStatement:
+                        await CommitAsyncLocked(ct);
+                        return 0;
+                    case RollbackTransactionStatement:
+                        await RollbackAsyncLocked(ct);
+                        return 0;
+                }
+
+                if (_txn is not null)
+                {
+                    // Inside an explicit transaction — buffer into it.
+                    _executor!.SetActiveAccess(new TxnKvAccess(_txn));
+                    return await _executor!.ExecuteAsync(stmt, parameters, ct);
+                }
+
+                // Implicit per-statement transaction so multi-key writes (row +
+                // index entries + IDENTITY counter) are atomic. CosmoKv's writer
+                // batches the buffer into one append, so the cost of the wrap
+                // is small.
+                var t = _db!.BeginTransaction(update: true);
+                try
+                {
+                    _executor!.SetActiveAccess(new TxnKvAccess(t));
+                    int n = await _executor!.ExecuteAsync(stmt, parameters, ct);
+                    await t.CommitAsync(ct);
+                    return n;
+                }
+                catch (global::CosmoKv.ConflictException ce)
+                {
+                    throw new SqlTransactionConflictException(
+                        "Implicit transaction failed due to a concurrent write conflict.", ce);
+                }
+                finally
+                {
+                    await t.DisposeAsync();
+                }
             }
             finally
             {
-                await t.DisposeAsync();
+                _executor?.SetActiveAccess(null);
             }
         }
-        finally
-        {
-            _executor?.SetActiveAccess(null);
-            _lock.Release();
-        }
     }
 
     public async Task<SqlDataTable> QueryTableAsync(
@@ -336,23 +342,20 @@ private static IReadOnlyList<SqlRow> MaterializeRows(
 
     public async Task BeginTransactionAsync(CancellationToken ct = default)
     {
-        await _lock.WaitAsync(ct);
-        try { await BeginTransactionAsyncLocked(ct); }
-        finally { _lock.Release(); }
+        using (await _rwLock.WriteLockAsync(ct))
+            await BeginTransactionAsyncLocked(ct);
     }
 
     public async Task CommitAsync(CancellationToken ct = default)
     {
-        await _lock.WaitAsync(ct);
-        try { await CommitAsyncLocked(ct); }
-        finally { _lock.Release(); }
+        using (await _rwLock.WriteLockAsync(ct))
+            await CommitAsyncLocked(ct);
     }
 
     public async Task RollbackAsync(CancellationToken ct = default)
     {
-        await _lock.WaitAsync(ct);
-        try { await RollbackAsyncLocked(ct); }
-        finally { _lock.Release(); }
+        using (await _rwLock.WriteLockAsync(ct))
+            await RollbackAsyncLocked(ct);
     }
 
     // ── Transaction internals (lock already held by caller) ─────────────────
@@ -421,7 +424,9 @@ public async ValueTask DisposeAsync()
         if (_disposed) return;
         _disposed = true;
         await CloseAsync();
-        _lock.Dispose();
+        // MS AsyncReaderWriterLock implements IDisposable internally only
+        // via its CompleteAsync API; GC handles cleanup of pending nodes
+        // once no references remain. No explicit dispose call needed.
     }
 
     private void EnsureOpen()

src/CosmoSQLClient.CosmoKv/CosmoSQLClient.CosmoKv.csproj

@@ -6,6 +6,12 @@
 
   <ItemGroup>
     <PackageReference Include="CosmoKv" Version="2.1.9" />
+    <!-- Microsoft.VisualStudio.Threading.AsyncReaderWriterLock — battle-
+         tested writer-priority RW lock for the CosmoKvConnection
+         hot path. The v2.5.7 attempt at rolling our own failed under
+         writer starvation; this primitive ships with cooperative
+         cancellation and bounded fairness already correct. -->
+    <PackageReference Include="Microsoft.VisualStudio.Threading" Version="17.14.15" />
   </ItemGroup>
 
   <PropertyGroup>