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);
    }
}
