namespace QuantEngine.Core.Interfaces;

/// <summary>
/// Provides point-in-time price history access with structural lookahead-bias prevention.
///
/// All methods enforce: trade_date &lt;= asOfDate is guaranteed by SQL WHERE clause,
/// not by client-side filtering. This structural guarantee prevents any code path
/// from accidentally accessing future data relative to the computation date.
/// </summary>
public interface IPriceHistoryReader
{
    /// <summary>
    /// Returns up to <paramref name="lookback"/> daily bars for <paramref name="ticker"/>
    /// with trade_date &lt;= <paramref name="asOfDate"/>, ordered most-recent-first.
    ///
    /// GUARANTEE: Never returns a bar dated after asOfDate — enforced by SQL WHERE clause.
    /// </summary>
    /// <param name="ticker">Stock ticker symbol</param>
    /// <param name="asOfDate">Observation date (inclusive upper bound)</param>
    /// <param name="lookback">Maximum number of bars to return</param>
    /// <returns>List of PriceHistoryDailyRecord, most-recent-first</returns>
    Task<List<PriceHistoryDailyRecord>> GetBarsAsOf(string ticker, DateOnly asOfDate, int lookback);
}
