CQRS support 3 new packages new docs

Author: MPCoreDeveloper

.github/CI_STATUS.md

@@ -75,42 +75,42 @@ After CI passes on master:
 
 ### 2. Publish to NuGet.org
 ```bash
-# Use the correct order (see docs/RELEASE_CHECKLIST_v1.5.0.md)
+# Use the correct order (see docs/RELEASE_CHECKLIST_v1.6.0.md)
 
 # Wave 1: Core
-dotnet nuget push "SharpCoreDB.1.5.0.nupkg" -k <api-key> -s https://api.nuget.org/v3/index.json
+dotnet nuget push "SharpCoreDB.1.6.0.nupkg" -k <api-key> -s https://api.nuget.org/v3/index.json
 
 # Wave 2: Direct dependencies (wait 60 seconds after Wave 1)
-dotnet nuget push "SharpCoreDB.Analytics.1.5.0.nupkg" -k <api-key> -s https://api.nuget.org/v3/index.json
-dotnet nuget push "SharpCoreDB.Data.Provider.1.5.0.nupkg" -k <api-key> -s https://api.nuget.org/v3/index.json
-dotnet nuget push "SharpCoreDB.Extensions.1.5.0.nupkg" -k <api-key> -s https://api.nuget.org/v3/index.json
-dotnet nuget push "SharpCoreDB.Graph.1.5.0.nupkg" -k <api-key> -s https://api.nuget.org/v3/index.json
-dotnet nuget push "SharpCoreDB.Distributed.1.5.0.nupkg" -k <api-key> -s https://api.nuget.org/v3/index.json
-dotnet nuget push "SharpCoreDB.VectorSearch.1.5.0.nupkg" -k <api-key> -s https://api.nuget.org/v3/index.json
-dotnet nuget push "SharpCoreDB.Serilog.Sinks.1.5.0.nupkg" -k <api-key> -s https://api.nuget.org/v3/index.json
+dotnet nuget push "SharpCoreDB.Analytics.1.6.0.nupkg" -k <api-key> -s https://api.nuget.org/v3/index.json
+dotnet nuget push "SharpCoreDB.Data.Provider.1.6.0.nupkg" -k <api-key> -s https://api.nuget.org/v3/index.json
+dotnet nuget push "SharpCoreDB.Extensions.1.6.0.nupkg" -k <api-key> -s https://api.nuget.org/v3/index.json
+dotnet nuget push "SharpCoreDB.Graph.1.6.0.nupkg" -k <api-key> -s https://api.nuget.org/v3/index.json
+dotnet nuget push "SharpCoreDB.Distributed.1.6.0.nupkg" -k <api-key> -s https://api.nuget.org/v3/index.json
+dotnet nuget push "SharpCoreDB.VectorSearch.1.6.0.nupkg" -k <api-key> -s https://api.nuget.org/v3/index.json
+dotnet nuget push "SharpCoreDB.Serilog.Sinks.1.6.0.nupkg" -k <api-key> -s https://api.nuget.org/v3/index.json
 
 # Wave 3: Multi-dependencies (wait 60 seconds after Wave 2)
-dotnet nuget push "SharpCoreDB.Provider.Sync.1.5.0.nupkg" -k <api-key> -s https://api.nuget.org/v3/index.json
-dotnet nuget push "SharpCoreDB.Provider.YesSql.1.5.0.nupkg" -k <api-key> -s https://api.nuget.org/v3/index.json
-dotnet nuget push "SharpCoreDB.EntityFrameworkCore.1.5.0.nupkg" -k <api-key> -s https://api.nuget.org/v3/index.json
+dotnet nuget push "SharpCoreDB.Provider.Sync.1.6.0.nupkg" -k <api-key> -s https://api.nuget.org/v3/index.json
+dotnet nuget push "SharpCoreDB.Provider.YesSql.1.6.0.nupkg" -k <api-key> -s https://api.nuget.org/v3/index.json
+dotnet nuget push "SharpCoreDB.EntityFrameworkCore.1.6.0.nupkg" -k <api-key> -s https://api.nuget.org/v3/index.json
 ```
 
 ### 3. Create GitHub Release
 ```bash
-git tag v1.5.0
-git push origin v1.5.0
+git tag v1.6.0
+git push origin v1.6.0
 ```
 
 Then create release on GitHub with:
-- Tag: `v1.5.0`
-- Title: `SharpCoreDB v1.5.0 - Critical Bug Fixes & Metadata Compression`
-- Description: Link to `docs/PROGRESSION_V1.3.5_TO_v1.5.0.md`
+- Tag: `v1.6.0`
+- Title: `SharpCoreDB v1.6.0 - Critical Bug Fixes & Metadata Compression`
+- Description: Link to `docs/PROGRESSION_V1.3.5_TO_v1.6.0.md`
 
 ## 🔗 Related Documentation
 
-- [Release Checklist](../docs/RELEASE_CHECKLIST_v1.5.0.md)
-- [Version Update Summary](../docs/VERSION_UPDATE_SUMMARY_v1.5.0.md)
-- [Progression Report](../docs/PROGRESSION_V1.3.5_TO_v1.5.0.md)
+- [Release Checklist](../docs/RELEASE_CHECKLIST_v1.6.0.md)
+- [Version Update Summary](../docs/VERSION_UPDATE_SUMMARY_v1.6.0.md)
+- [Progression Report](../docs/PROGRESSION_V1.3.5_TO_v1.6.0.md)
 
 ## 🐛 Troubleshooting
 
@@ -123,11 +123,11 @@ Then create release on GitHub with:
 - Check test output in GitHub Actions artifacts
 
 ### Pack Failures
-- Ensure all dependencies are v1.5.0
+- Ensure all dependencies are v1.6.0
 - Check for missing NuGet.README.md files
 
 ---
 
 **Last Updated:** 2026-02-28  
-**Version:** 1.5.0  
+**Version:** 1.6.0  
 **Status:** ✅ Fully Operational with .NET 10 SDK

.github/copilot-instructions.md

@@ -5,7 +5,8 @@
 - All project documentation must be written in English. This includes docs, README files, technical specs, implementation plans, and code comments.
 - Provide periodic progress updates while work is ongoing to ensure the assistant is not stuck.
 - When benchmarking competitor databases (like BLite), document the developer experience (DX) honestly. If a library's API is hard to use, poorly documented, or has mismatches between docs and actual API, note that as a real finding in the benchmark report. User-friendliness and ease of integration matter as much as raw performance numbers.
-- Standardize all documentation/version labels to v1.5.0 ("V 1.50").
+- Standardize all documentation/version labels to v1.6.0 ("V 1.60").
+- Continue implementation until the scoped roadmap work is finished without pausing for confirmation.
 
 ## Testing Policy
 - All test projects in SharpCoreDB must use **xUnit v3** (`xunit.v3` NuGet package, currently 3.2.2+). **Never** use `xunit` v2 (package id `xunit`). The old v2 package is incompatible with .NET 10 / C# 14.
@@ -34,6 +35,7 @@
 - New SharpCoreDB features must remain optional; event sourcing must be delivered as a separate NuGet package, and issue-driven user features should be prioritized ahead of server mode work.
 - Event sourcing must support both persistent storage and the existing in-memory option; provide an additional demo example specifically for persistent storage.
 - Prioritize gRPC as the flagship protocol for SharpCoreDB.Server; binary/HTTP are secondary.
+- SharpCoreDB roadmap priority: make Event Sourcing first-class, add native snapshots, then projection engine; keep ES/CQRS optional packages, .NET 10-native, zero external deps in core, and gRPC-first networked server integration.
 
 ## Asynchronous Programming Guidelines
 - When fixing cancellation token handling in parallel async methods that use `Parallel.ForEachAsync`, always wrap the parallel operation in a try-catch block to properly propagate `OperationCanceledException`. The `CancellationToken` passed to `ParallelOptions` will cause an `OperationCanceledException` to be thrown from `Parallel.ForEachAsync`, and this must be caught and re-thrown to ensure proper cancellation propagation to calling code.

Examples/EventSourcing/OrderManagement.PersistentDemo/OrderManagement.PersistentDemo.csproj

@@ -6,7 +6,7 @@
     <LangVersion>14.0</LangVersion>
     <ImplicitUsings>enable</ImplicitUsings>
     <Nullable>enable</Nullable>
-    <Version>1.5.0</Version>
+    <Version>1.6.0</Version>
     <IsPackable>false</IsPackable>
   </PropertyGroup>
 

Examples/EventSourcing/OrderManagement/OrderAggregate.cs

@@ -5,6 +5,7 @@
 
 namespace OrderManagement;
 
+using System.Text.Json;
 using SharpCoreDB.EventSourcing;
 
 /// <summary>
@@ -212,15 +213,72 @@ public void CancelOrder(string reason, string cancelledBy)
     public static OrderAggregate FromEventStream(IReadOnlyList<EventEnvelope> events)
     {
         var aggregate = new OrderAggregate();
-        
+        aggregate.Replay(events);
+        return aggregate;
+    }
+
+    /// <summary>
+    /// Rehydrates aggregate from snapshot payload.
+    /// </summary>
+    /// <param name="snapshotData">Serialized snapshot bytes.</param>
+    /// <returns>Rehydrated aggregate.</returns>
+    public static OrderAggregate FromSnapshot(ReadOnlyMemory<byte> snapshotData)
+    {
+        var snapshot = JsonSerializer.Deserialize<OrderSnapshotState>(snapshotData.Span)
+            ?? throw new InvalidOperationException("Failed to deserialize order snapshot.");
+
+        return new OrderAggregate
+        {
+            OrderId = snapshot.OrderId,
+            CustomerId = snapshot.CustomerId,
+            Status = snapshot.Status,
+            Items = snapshot.Items,
+            TotalAmount = snapshot.TotalAmount,
+            TrackingNumber = snapshot.TrackingNumber,
+            PaymentTransactionId = snapshot.PaymentTransactionId,
+            DeliveredAt = snapshot.DeliveredAt,
+            Version = snapshot.Version,
+        };
+    }
+
+    /// <summary>
+    /// Serializes current aggregate state as snapshot payload.
+    /// </summary>
+    /// <param name="version">Version to persist in snapshot metadata.</param>
+    /// <returns>Serialized snapshot bytes.</returns>
+    public byte[] ToSnapshotData(long version)
+    {
+        var snapshot = new OrderSnapshotState
+        {
+            OrderId = OrderId,
+            CustomerId = CustomerId,
+            Status = Status,
+            Items = [.. Items],
+            TotalAmount = TotalAmount,
+            TrackingNumber = TrackingNumber,
+            PaymentTransactionId = PaymentTransactionId,
+            DeliveredAt = DeliveredAt,
+            Version = version,
+        };
+
+        return JsonSerializer.SerializeToUtf8Bytes(snapshot);
+    }
+
+    /// <summary>
+    /// Replays additional envelopes into current aggregate state.
+    /// </summary>
+    /// <param name="events">Event envelopes to apply.</param>
+    /// <returns>Current aggregate instance.</returns>
+    public OrderAggregate Replay(IReadOnlyList<EventEnvelope> events)
+    {
         foreach (var envelope in events)
         {
             var orderEvent = DeserializeEvent(envelope);
-            aggregate.Apply(orderEvent);
-            aggregate.Version = envelope.Sequence;
+            Apply(orderEvent);
+            Version = envelope.Sequence;
         }
-        
-        return aggregate;
+
+        return this;
     }
 
     /// <summary>
@@ -324,4 +382,25 @@ private static OrderEvent DeserializeEvent(EventEnvelope envelope)
             _ => throw new InvalidOperationException($"Unknown event type: {envelope.EventType}")
         };
     }
+
+    private sealed class OrderSnapshotState
+    {
+        public required string OrderId { get; init; }
+
+        public required string CustomerId { get; init; }
+
+        public required OrderStatus Status { get; init; }
+
+        public required List<OrderItem> Items { get; init; }
+
+        public required decimal TotalAmount { get; init; }
+
+        public required string? TrackingNumber { get; init; }
+
+        public required string? PaymentTransactionId { get; init; }
+
+        public required DateTimeOffset? DeliveredAt { get; init; }
+
+        public required long Version { get; init; }
+    }
 }

Examples/EventSourcing/OrderManagement/OrderManagement.csproj

@@ -6,7 +6,7 @@
     <LangVersion>14.0</LangVersion>
     <ImplicitUsings>enable</ImplicitUsings>
     <Nullable>enable</Nullable>
-    <Version>1.5.0</Version>
+    <Version>1.6.0</Version>
     <IsPackable>false</IsPackable>
   </PropertyGroup>