backtest-kit 2.2.26 → 2.3.2

package/README.md

@@ -205,14 +205,109 @@ Backtest Kit is **not a data-processing library** - it is a **time execution eng
 
 ### 🔍 How getCandles Works
 
-backtest-kit uses Node.js `AsyncLocalStorage` to automatically provide 
-temporal time context to your strategies. Exclusive (aka `[startTime, endTime)`) candle limit being used
+backtest-kit uses Node.js `AsyncLocalStorage` to automatically provide
+temporal time context to your strategies.
+
+  <details>
+    <summary>
+      The Math
+    </summary>
+
+    For a candle with:
+    - `timestamp` = candle open time (openTime)
+    - `stepMs` = interval duration (e.g., 60000ms for "1m")
+    - Candle close time = `timestamp + stepMs`
+
+    **Alignment:** All timestamps are aligned down to interval boundary.
+    For example, for 15m interval: 00:17 → 00:15, 00:44 → 00:30
+
+    **Adapter contract:**
+    - First candle.timestamp must equal aligned `since`
+    - Adapter must return exactly `limit` candles
+    - Sequential timestamps: `since + i * stepMs` for i = 0..limit-1
+
+    - `getCandles(symbol, interval, limit)` - Returns exactly `limit` candles
+      - Aligns `when` down to interval boundary
+      - Calculates `since = alignedWhen - limit * stepMs`
+      - First candle.timestamp === since
+      - Example: `getCandles("BTCUSDT", "1m", 100)` returns 100 candles ending at aligned when
+
+    - `getNextCandles(symbol, interval, limit)` - Returns exactly `limit` candles (backtest only)
+      - Aligns `when` down to interval boundary
+      - `since = alignedWhen` (starts from aligned when, going forward)
+      - First candle.timestamp === since
+      - Throws error in live mode to prevent look-ahead bias
+      - Example: `getNextCandles("BTCUSDT", "1m", 10)` returns next 10 candles after aligned when
+
+    - `getRawCandles(symbol, interval, limit?, sDate?, eDate?)` - Flexible parameter combinations:
+      - `(limit)` - since = alignedWhen - limit * stepMs
+      - `(limit, sDate)` - since = align(sDate), returns `limit` candles forward
+      - `(limit, undefined, eDate)` - since = align(eDate) - limit * stepMs
+      - `(undefined, sDate, eDate)` - since = align(sDate), limit calculated from range
+      - `(limit, sDate, eDate)` - since = align(sDate), returns `limit` candles
+      - All combinations respect look-ahead bias protection (eDate/endTime <= when)
+
+    **Persistent Cache:**
+    - Cache lookup calculates expected timestamps: `since + i * stepMs` for i = 0..limit-1
+    - Returns all candles if found, null if any missing (cache miss)
+    - Cache and runtime use identical timestamp calculation logic
+
+  </details>
+
+#### Candle Timestamp Convention:
+
+According to this `timestamp` of a candle in backtest-kit is exactly the `openTime`, not ~~`closeTime`~~
+
+**Key principles:**
+- All timestamps are aligned down to interval boundary
+- First candle.timestamp must equal aligned `since`
+- Adapter must return exactly `limit` candles
+- Sequential timestamps: `since + i * stepMs`
+
+### 🔬 Technical Details: Timestamp Alignment
+
+**Why align timestamps to interval boundaries?**
+
+Because candle APIs return data starting from exact interval boundaries:
+
+```typescript
+// 15-minute interval example:
+when = 1704067920000       // 00:12:00
+step = 15                  // 15 minutes
+stepMs = 15 * 60000        // 900000ms
+
+// Alignment: round down to nearest interval boundary
+alignedWhen = Math.floor(when / stepMs) * stepMs
+// = Math.floor(1704067920000 / 900000) * 900000
+// = 1704067200000 (00:00:00)
+
+// Calculate since for 4 candles backwards:
+since = alignedWhen - 4 * stepMs
+// = 1704067200000 - 4 * 900000
+// = 1704063600000 (23:00:00 previous day)
+
+// Expected candles:
+// [0] timestamp = 1704063600000 (23:00)
+// [1] timestamp = 1704064500000 (23:15)
+// [2] timestamp = 1704065400000 (23:30)
+// [3] timestamp = 1704066300000 (23:45)
+```
+
+**Validation is applied consistently across:**
+- ✅ `getCandles()` - validates first timestamp and count
+- ✅ `getNextCandles()` - validates first timestamp and count
+- ✅ `getRawCandles()` - validates first timestamp and count
+- ✅ Cache read - calculates exact expected timestamps
+- ✅ Cache write - stores validated candles
+
+**Result:** Deterministic candle retrieval with exact timestamp matching.
 
 ### 💭 What this means:
 - `getCandles()` always returns data UP TO the current backtest timestamp using `async_hooks`
 - Multi-timeframe data is automatically synchronized
-- **Impossible to introduce look-ahead bias**
+- **Impossible to introduce look-ahead bias** - all time boundaries are enforced
 - Same code works in both backtest and live modes
+- Boundary semantics prevent edge cases in signal generation
 
 
 ## 🧠 Two Ways to Run the Engine