feat(quant): WBS-FE-BE-100 complete Vue3 Vite8 SPA & .NET10 FastEndpoints refactoring

src/dotnet/QuantEngine.Core/Interfaces/IPostgresqlHistoryStore.cs

@@ -1,11 +1,33 @@
+using System;
 using System.Collections.Generic;
 using System.Threading.Tasks;
 
 namespace QuantEngine.Core.Interfaces
 {
+    /// <summary>
+    /// Core Domain Interface for PostgreSQL History-First Operating Model.
+    /// Strictly enforces SOLID principles, 3NF Data Integrity, and Provenance Payload Tracking.
+    /// </summary>
     public interface IPostgresqlHistoryStore
     {
+        /// <summary>
+        /// Appends a raw market or factor history record to PostgreSQL with JSONB Provenance.
+        /// </summary>
         Task<int> AppendAsync(string domain, IDictionary<string, object?> payload);
+
+        /// <summary>
+        /// Retrieves the latest versioned snapshot for a given operational history domain.
+        /// </summary>
         Task<IReadOnlyList<IDictionary<string, object?>>> SnapshotAsync(string domain, int limit = 500);
+
+        /// <summary>
+        /// Records a sell strategy waterfall execution step for auditability and game-theoretic risk tracking.
+        /// </summary>
+        Task<long> RecordWaterfallExecutionAsync(string runId, string ticker, int rank, string stage, string action, int targetQty, decimal? targetPrice, decimal? bidAskSpreadBps, decimal? slippageBps, string status, string rationale);
+
+        /// <summary>
+        /// Records a blocked order or gate restriction to the Shadow Ledger without hiding calculation values.
+        /// </summary>
+        Task<long> RecordShadowLedgerAsync(string runId, string ticker, string blockedGate, string blockedReason, decimal shadowPrice, int shadowQty, decimal? shadowTpPrice, decimal? shadowSlPrice);
     }
 }