backtest-kit 1.2.0 → 1.2.1

package/README.md

@@ -12,7 +12,7 @@ Build sophisticated trading systems with confidence. Backtest Kit empowers you t
 
 ## ✨ Why Choose Backtest Kit?
 
-- 🚀 **Production-Ready Architecture**: Seamlessly switch between backtest and live modes with robust error recovery and graceful shutdown mechanisms. Your strategy code remains identical across environments. ✅
+- 🚀 **Production-Ready Architecture**: Seamlessly switch between backtest and live modes with robust error recovery and graceful shutdown mechanisms. Your strategy code remains identical across environments. 
 
 - 💾 **Crash-Safe Persistence**: Atomic file writes with automatic state recovery ensure no duplicate signals or lost data—even after crashes. Resume execution exactly where you left off. 🔄
 
@@ -46,7 +46,7 @@ Build sophisticated trading systems with confidence. Backtest Kit empowers you t
 
 - 🔒 **Safe Math & Robustness**: All metrics protected against NaN/Infinity with unsafe numeric checks. Returns N/A for invalid calculations. ✨
 
-- 🧪 **Comprehensive Test Coverage**: 123 unit and integration tests covering validation, PNL, callbacks, reports, performance tracking, walker, heatmap, position sizing, risk management, scheduled signals, and event system. ✅
+- 🧪 **Comprehensive Test Coverage**: 123 unit and integration tests covering validation, PNL, callbacks, reports, performance tracking, walker, heatmap, position sizing, risk management, scheduled signals, and event system. 
 
 ---
 
@@ -227,6 +227,7 @@ Backtest.background("BTCUSDT", {
 - 🛡️ **Signal Lifecycle**: Type-safe state machine prevents invalid state transitions. 🚑
 - 📦 **Dependency Inversion**: Lazy-load components at runtime for modular, scalable designs. 🧩
 - 🔍 **Schema Reflection**: Runtime introspection with `listExchanges()`, `listStrategies()`, `listFrames()`. 📊
+- 🔬 **Data Validation**: Automatic detection and rejection of incomplete candles from Binance API with anomaly checks. 
 
 ---
 
@@ -261,7 +262,7 @@ Check out the sections below for detailed examples! 📚
 
 ### 1. Register Exchange Data Source
 
-You can plug any data source—CCXT for live data or a database for faster backtesting:
+You can plug any data source: CCXT for live data or a database for faster backtesting:
 
 ```typescript
 import { addExchange } from "backtest-kit";

package/build/index.cjs

@@ -37,6 +37,44 @@ const GLOBAL_CONFIG = {
      * Default: 1440 minutes (1 day)
      */
     CC_MAX_SIGNAL_LIFETIME_MINUTES: 1440,
+    /**
+     * Number of retries for getCandles function
+     * Default: 3 retries
+     */
+    CC_GET_CANDLES_RETRY_COUNT: 3,
+    /**
+     * Delay between retries for getCandles function (in milliseconds)
+     * Default: 5000 ms (5 seconds)
+     */
+    CC_GET_CANDLES_RETRY_DELAY_MS: 5000,
+    /**
+     * Maximum allowed deviation factor for price anomaly detection.
+     * Price should not be more than this factor lower than reference price.
+     *
+     * Reasoning:
+     * - Incomplete candles from Binance API typically have prices near 0 (e.g., $0.01-1)
+     * - Normal BTC price ranges: $20,000-100,000
+     * - Factor 1000 catches prices below $20-100 when median is $20,000-100,000
+     * - Factor 100 would be too permissive (allows $200 when median is $20,000)
+     * - Factor 10000 might be too strict for low-cap altcoins
+     *
+     * Example: BTC at $50,000 median → threshold $50 (catches $0.01-1 anomalies)
+     */
+    CC_GET_CANDLES_PRICE_ANOMALY_THRESHOLD_FACTOR: 1000,
+    /**
+     * Minimum number of candles required for reliable median calculation.
+     * Below this threshold, use simple average instead of median.
+     *
+     * Reasoning:
+     * - Each candle provides 4 price points (OHLC)
+     * - 5 candles = 20 price points, sufficient for robust median calculation
+     * - Below 5 candles, single anomaly can heavily skew median
+     * - Statistical rule of thumb: minimum 7-10 data points for median stability
+     * - Average is more stable than median for small datasets (n < 20)
+     *
+     * Example: 3 candles = 12 points (use average), 5 candles = 20 points (use median)
+     */
+    CC_GET_CANDLES_MIN_CANDLES_FOR_MEDIAN: 5,
 };
 
 const { init, inject, provide } = diKit.createActivator("backtest");
@@ -271,6 +309,92 @@ const INTERVAL_MINUTES$2 = {
     "6h": 360,
     "8h": 480,
 };
+/**
+ * Validates that all candles have valid OHLCV data without anomalies.
+ * Detects incomplete candles from Binance API by checking for abnormally low prices or volumes.
+ * Incomplete candles often have prices like 0.1 instead of normal 100,000 or zero volume.
+ *
+ * @param candles - Array of candle data to validate
+ * @throws Error if any candles have anomalous OHLCV values
+ */
+const VALIDATE_NO_INCOMPLETE_CANDLES_FN = (candles) => {
+    if (candles.length === 0) {
+        return;
+    }
+    // Calculate reference price (median or average depending on candle count)
+    const allPrices = candles.flatMap((c) => [c.open, c.high, c.low, c.close]);
+    const validPrices = allPrices.filter(p => p > 0);
+    let referencePrice;
+    if (candles.length >= GLOBAL_CONFIG.CC_GET_CANDLES_MIN_CANDLES_FOR_MEDIAN) {
+        // Use median for reliable statistics with enough data
+        const sortedPrices = [...validPrices].sort((a, b) => a - b);
+        referencePrice = sortedPrices[Math.floor(sortedPrices.length / 2)] || 0;
+    }
+    else {
+        // Use average for small datasets (more stable than median)
+        const sum = validPrices.reduce((acc, p) => acc + p, 0);
+        referencePrice = validPrices.length > 0 ? sum / validPrices.length : 0;
+    }
+    if (referencePrice === 0) {
+        throw new Error(`VALIDATE_NO_INCOMPLETE_CANDLES_FN: cannot calculate reference price (all prices are zero)`);
+    }
+    const minValidPrice = referencePrice / GLOBAL_CONFIG.CC_GET_CANDLES_PRICE_ANOMALY_THRESHOLD_FACTOR;
+    for (let i = 0; i < candles.length; i++) {
+        const candle = candles[i];
+        // Check for invalid numeric values
+        if (!Number.isFinite(candle.open) ||
+            !Number.isFinite(candle.high) ||
+            !Number.isFinite(candle.low) ||
+            !Number.isFinite(candle.close) ||
+            !Number.isFinite(candle.volume) ||
+            !Number.isFinite(candle.timestamp)) {
+            throw new Error(`VALIDATE_NO_INCOMPLETE_CANDLES_FN: candle[${i}] has invalid numeric values (NaN or Infinity)`);
+        }
+        // Check for negative values
+        if (candle.open <= 0 ||
+            candle.high <= 0 ||
+            candle.low <= 0 ||
+            candle.close <= 0 ||
+            candle.volume < 0) {
+            throw new Error(`VALIDATE_NO_INCOMPLETE_CANDLES_FN: candle[${i}] has zero or negative values`);
+        }
+        // Check for anomalously low prices (incomplete candle indicator)
+        if (candle.open < minValidPrice ||
+            candle.high < minValidPrice ||
+            candle.low < minValidPrice ||
+            candle.close < minValidPrice) {
+            throw new Error(`VALIDATE_NO_INCOMPLETE_CANDLES_FN: candle[${i}] has anomalously low price. ` +
+                `OHLC: [${candle.open}, ${candle.high}, ${candle.low}, ${candle.close}], ` +
+                `reference: ${referencePrice}, threshold: ${minValidPrice}`);
+        }
+    }
+};
+/**
+ * Retries the getCandles function with specified retry count and delay.
+ * @param dto - Data transfer object containing symbol, interval, and limit
+ * @param since - Date object representing the start time for fetching candles
+ * @param self - Instance of ClientExchange
+ * @returns Promise resolving to array of candle data
+ */
+const GET_CANDLES_FN = async (dto, since, self) => {
+    let lastError;
+    for (let i = 0; i !== GLOBAL_CONFIG.CC_GET_CANDLES_RETRY_COUNT; i++) {
+        try {
+            const result = await self.params.getCandles(dto.symbol, dto.interval, since, dto.limit);
+            VALIDATE_NO_INCOMPLETE_CANDLES_FN(result);
+            return result;
+        }
+        catch (err) {
+            self.params.logger.warn(`ClientExchange GET_CANDLES_FN: attempt ${i + 1} failed for symbol=${dto.symbol}, interval=${dto.interval}, since=${since.toISOString()}, limit=${dto.limit}}`, {
+                error: functoolsKit.errorData(err),
+                message: functoolsKit.getErrorMessage(err),
+            });
+            lastError = err;
+            await functoolsKit.sleep(GLOBAL_CONFIG.CC_GET_CANDLES_RETRY_DELAY_MS);
+        }
+    }
+    throw lastError;
+};
 /**
  * Client implementation for exchange data access.
  *
@@ -321,7 +445,7 @@ class ClientExchange {
             throw new Error(`ClientExchange unknown time adjust for interval=${interval}`);
         }
         const since = new Date(this.params.execution.context.when.getTime() - adjust * 60 * 1000);
-        const data = await this.params.getCandles(symbol, interval, since, limit);
+        const data = await GET_CANDLES_FN({ symbol, interval, limit }, since, this);
         // Filter candles to strictly match the requested range
         const whenTimestamp = this.params.execution.context.when.getTime();
         const sinceTimestamp = since.getTime();
@@ -359,7 +483,7 @@ class ClientExchange {
         if (endTime > now) {
             return [];
         }
-        const data = await this.params.getCandles(symbol, interval, since, limit);
+        const data = await GET_CANDLES_FN({ symbol, interval, limit }, since, this);
         // Filter candles to strictly match the requested range
         const sinceTimestamp = since.getTime();
         const filteredData = data.filter((candle) => candle.timestamp >= sinceTimestamp && candle.timestamp <= endTime);
@@ -1126,7 +1250,7 @@ class PersistSignalUtils {
      *   async readValue(id) { return JSON.parse(await redis.get(id)); }
      *   async writeValue(id, entity) { await redis.set(id, JSON.stringify(entity)); }
      * }
-     * PersistSignalAdaper.usePersistSignalAdapter(RedisPersist);
+     * PersistSignalAdapter.usePersistSignalAdapter(RedisPersist);
      * ```
      */
     usePersistSignalAdapter(Ctor) {
@@ -1141,16 +1265,16 @@ class PersistSignalUtils {
  * @example
  * ```typescript
  * // Custom adapter
- * PersistSignalAdaper.usePersistSignalAdapter(RedisPersist);
+ * PersistSignalAdapter.usePersistSignalAdapter(RedisPersist);
  *
  * // Read signal
- * const signal = await PersistSignalAdaper.readSignalData("my-strategy", "BTCUSDT");
+ * const signal = await PersistSignalAdapter.readSignalData("my-strategy", "BTCUSDT");
  *
  * // Write signal
- * await PersistSignalAdaper.writeSignalData(signal, "my-strategy", "BTCUSDT");
+ * await PersistSignalAdapter.writeSignalData(signal, "my-strategy", "BTCUSDT");
  * ```
  */
-const PersistSignalAdaper = new PersistSignalUtils();
+const PersistSignalAdapter = new PersistSignalUtils();
 const PERSIST_RISK_UTILS_METHOD_NAME_USE_PERSIST_RISK_ADAPTER = "PersistRiskUtils.usePersistRiskAdapter";
 const PERSIST_RISK_UTILS_METHOD_NAME_READ_DATA = "PersistRiskUtils.readPositionData";
 const PERSIST_RISK_UTILS_METHOD_NAME_WRITE_DATA = "PersistRiskUtils.writePositionData";
@@ -1523,7 +1647,7 @@ const WAIT_FOR_INIT_FN$1 = async (self) => {
     if (self.params.execution.context.backtest) {
         return;
     }
-    const pendingSignal = await PersistSignalAdaper.readSignalData(self.params.strategyName, self.params.execution.context.symbol);
+    const pendingSignal = await PersistSignalAdapter.readSignalData(self.params.strategyName, self.params.execution.context.symbol);
     if (!pendingSignal) {
         return;
     }
@@ -1985,25 +2109,33 @@ const PROCESS_SCHEDULED_SIGNAL_CANDLES_FN = async (self, scheduled, candles) =>
         let shouldActivate = false;
         let shouldCancel = false;
         if (scheduled.position === "long") {
-            // КРИТИЧНО: Сначала проверяем StopLoss (отмена приоритетнее активации)
-            // Отмена если цена упала СЛИШКОМ низко (ниже SL)
+            // КРИТИЧНО для LONG:
+            // - priceOpen > priceStopLoss (по валидации)
+            // - Активация: low <= priceOpen (цена упала до входа)
+            // - Отмена: low <= priceStopLoss (цена пробила SL)
+            //
+            // EDGE CASE: если low <= priceStopLoss И low <= priceOpen на ОДНОЙ свече:
+            // => Отмена имеет ПРИОРИТЕТ! (SL пробит ДО или ВМЕСТЕ с активацией)
+            // Сигнал НЕ открывается, сразу отменяется
             if (candle.low <= scheduled.priceStopLoss) {
                 shouldCancel = true;
             }
-            // Long = покупаем дешевле, ждем падения цены ДО priceOpen
-            // Активируем только если НЕ пробит StopLoss
             else if (candle.low <= scheduled.priceOpen) {
                 shouldActivate = true;
             }
         }
         if (scheduled.position === "short") {
-            // КРИТИЧНО: Сначала проверяем StopLoss (отмена приоритетнее активации)
-            // Отмена если цена выросла СЛИШКОМ высоко (выше SL)
+            // КРИТИЧНО для SHORT:
+            // - priceOpen < priceStopLoss (по валидации)
+            // - Активация: high >= priceOpen (цена выросла до входа)
+            // - Отмена: high >= priceStopLoss (цена пробила SL)
+            //
+            // EDGE CASE: если high >= priceStopLoss И high >= priceOpen на ОДНОЙ свече:
+            // => Отмена имеет ПРИОРИТЕТ! (SL пробит ДО или ВМЕСТЕ с активацией)
+            // Сигнал НЕ открывается, сразу отменяется
             if (candle.high >= scheduled.priceStopLoss) {
                 shouldCancel = true;
             }
-            // Short = продаем дороже, ждем роста цены ДО priceOpen
-            // Активируем только если НЕ пробит StopLoss
             else if (candle.high >= scheduled.priceOpen) {
                 shouldActivate = true;
             }
@@ -2143,10 +2275,15 @@ class ClientStrategy {
             pendingSignal,
         });
         this._pendingSignal = pendingSignal;
+        // КРИТИЧНО: Всегда вызываем коллбек onWrite для тестирования persist storage
+        // даже в backtest режиме, чтобы тесты могли перехватывать вызовы через mock adapter
+        if (this.params.callbacks?.onWrite) {
+            this.params.callbacks.onWrite(this.params.execution.context.symbol, this._pendingSignal, this.params.execution.context.backtest);
+        }
         if (this.params.execution.context.backtest) {
             return;
         }
-        await PersistSignalAdaper.writeSignalData(this._pendingSignal, this.params.strategyName, this.params.execution.context.symbol);
+        await PersistSignalAdapter.writeSignalData(this._pendingSignal, this.params.strategyName, this.params.execution.context.symbol);
     }
     /**
      * Performs a single tick of strategy execution.
@@ -10100,7 +10237,7 @@ exports.MethodContextService = MethodContextService;
 exports.Performance = Performance;
 exports.PersistBase = PersistBase;
 exports.PersistRiskAdapter = PersistRiskAdapter;
-exports.PersistSignalAdaper = PersistSignalAdaper;
+exports.PersistSignalAdapter = PersistSignalAdapter;
 exports.PositionSize = PositionSize;
 exports.Schedule = Schedule;
 exports.Walker = Walker;

package/build/index.mjs

@@ -1,6 +1,6 @@
 import { createActivator } from 'di-kit';
 import { scoped } from 'di-scoped';
-import { memoize, makeExtendable, singleshot, getErrorMessage, not, trycatch, retry, Subject, randomString, errorData, ToolRegistry, isObject, sleep, resolveDocuments, str, queued } from 'functools-kit';
+import { errorData, getErrorMessage, sleep, memoize, makeExtendable, singleshot, not, trycatch, retry, Subject, randomString, ToolRegistry, isObject, resolveDocuments, str, queued } from 'functools-kit';
 import fs, { mkdir, writeFile } from 'fs/promises';
 import path, { join } from 'path';
 import crypto from 'crypto';
@@ -35,6 +35,44 @@ const GLOBAL_CONFIG = {
      * Default: 1440 minutes (1 day)
      */
     CC_MAX_SIGNAL_LIFETIME_MINUTES: 1440,
+    /**
+     * Number of retries for getCandles function
+     * Default: 3 retries
+     */
+    CC_GET_CANDLES_RETRY_COUNT: 3,
+    /**
+     * Delay between retries for getCandles function (in milliseconds)
+     * Default: 5000 ms (5 seconds)
+     */
+    CC_GET_CANDLES_RETRY_DELAY_MS: 5000,
+    /**
+     * Maximum allowed deviation factor for price anomaly detection.
+     * Price should not be more than this factor lower than reference price.
+     *
+     * Reasoning:
+     * - Incomplete candles from Binance API typically have prices near 0 (e.g., $0.01-1)
+     * - Normal BTC price ranges: $20,000-100,000
+     * - Factor 1000 catches prices below $20-100 when median is $20,000-100,000
+     * - Factor 100 would be too permissive (allows $200 when median is $20,000)
+     * - Factor 10000 might be too strict for low-cap altcoins
+     *
+     * Example: BTC at $50,000 median → threshold $50 (catches $0.01-1 anomalies)
+     */
+    CC_GET_CANDLES_PRICE_ANOMALY_THRESHOLD_FACTOR: 1000,
+    /**
+     * Minimum number of candles required for reliable median calculation.
+     * Below this threshold, use simple average instead of median.
+     *
+     * Reasoning:
+     * - Each candle provides 4 price points (OHLC)
+     * - 5 candles = 20 price points, sufficient for robust median calculation
+     * - Below 5 candles, single anomaly can heavily skew median
+     * - Statistical rule of thumb: minimum 7-10 data points for median stability
+     * - Average is more stable than median for small datasets (n < 20)
+     *
+     * Example: 3 candles = 12 points (use average), 5 candles = 20 points (use median)
+     */
+    CC_GET_CANDLES_MIN_CANDLES_FOR_MEDIAN: 5,
 };
 
 const { init, inject, provide } = createActivator("backtest");
@@ -269,6 +307,92 @@ const INTERVAL_MINUTES$2 = {
     "6h": 360,
     "8h": 480,
 };
+/**
+ * Validates that all candles have valid OHLCV data without anomalies.
+ * Detects incomplete candles from Binance API by checking for abnormally low prices or volumes.
+ * Incomplete candles often have prices like 0.1 instead of normal 100,000 or zero volume.
+ *
+ * @param candles - Array of candle data to validate
+ * @throws Error if any candles have anomalous OHLCV values
+ */
+const VALIDATE_NO_INCOMPLETE_CANDLES_FN = (candles) => {
+    if (candles.length === 0) {
+        return;
+    }
+    // Calculate reference price (median or average depending on candle count)
+    const allPrices = candles.flatMap((c) => [c.open, c.high, c.low, c.close]);
+    const validPrices = allPrices.filter(p => p > 0);
+    let referencePrice;
+    if (candles.length >= GLOBAL_CONFIG.CC_GET_CANDLES_MIN_CANDLES_FOR_MEDIAN) {
+        // Use median for reliable statistics with enough data
+        const sortedPrices = [...validPrices].sort((a, b) => a - b);
+        referencePrice = sortedPrices[Math.floor(sortedPrices.length / 2)] || 0;
+    }
+    else {
+        // Use average for small datasets (more stable than median)
+        const sum = validPrices.reduce((acc, p) => acc + p, 0);
+        referencePrice = validPrices.length > 0 ? sum / validPrices.length : 0;
+    }
+    if (referencePrice === 0) {
+        throw new Error(`VALIDATE_NO_INCOMPLETE_CANDLES_FN: cannot calculate reference price (all prices are zero)`);
+    }
+    const minValidPrice = referencePrice / GLOBAL_CONFIG.CC_GET_CANDLES_PRICE_ANOMALY_THRESHOLD_FACTOR;
+    for (let i = 0; i < candles.length; i++) {
+        const candle = candles[i];
+        // Check for invalid numeric values
+        if (!Number.isFinite(candle.open) ||
+            !Number.isFinite(candle.high) ||
+            !Number.isFinite(candle.low) ||
+            !Number.isFinite(candle.close) ||
+            !Number.isFinite(candle.volume) ||
+            !Number.isFinite(candle.timestamp)) {
+            throw new Error(`VALIDATE_NO_INCOMPLETE_CANDLES_FN: candle[${i}] has invalid numeric values (NaN or Infinity)`);
+        }
+        // Check for negative values
+        if (candle.open <= 0 ||
+            candle.high <= 0 ||
+            candle.low <= 0 ||
+            candle.close <= 0 ||
+            candle.volume < 0) {
+            throw new Error(`VALIDATE_NO_INCOMPLETE_CANDLES_FN: candle[${i}] has zero or negative values`);
+        }
+        // Check for anomalously low prices (incomplete candle indicator)
+        if (candle.open < minValidPrice ||
+            candle.high < minValidPrice ||
+            candle.low < minValidPrice ||
+            candle.close < minValidPrice) {
+            throw new Error(`VALIDATE_NO_INCOMPLETE_CANDLES_FN: candle[${i}] has anomalously low price. ` +
+                `OHLC: [${candle.open}, ${candle.high}, ${candle.low}, ${candle.close}], ` +
+                `reference: ${referencePrice}, threshold: ${minValidPrice}`);
+        }
+    }
+};
+/**
+ * Retries the getCandles function with specified retry count and delay.
+ * @param dto - Data transfer object containing symbol, interval, and limit
+ * @param since - Date object representing the start time for fetching candles
+ * @param self - Instance of ClientExchange
+ * @returns Promise resolving to array of candle data
+ */
+const GET_CANDLES_FN = async (dto, since, self) => {
+    let lastError;
+    for (let i = 0; i !== GLOBAL_CONFIG.CC_GET_CANDLES_RETRY_COUNT; i++) {
+        try {
+            const result = await self.params.getCandles(dto.symbol, dto.interval, since, dto.limit);
+            VALIDATE_NO_INCOMPLETE_CANDLES_FN(result);
+            return result;
+        }
+        catch (err) {
+            self.params.logger.warn(`ClientExchange GET_CANDLES_FN: attempt ${i + 1} failed for symbol=${dto.symbol}, interval=${dto.interval}, since=${since.toISOString()}, limit=${dto.limit}}`, {
+                error: errorData(err),
+                message: getErrorMessage(err),
+            });
+            lastError = err;
+            await sleep(GLOBAL_CONFIG.CC_GET_CANDLES_RETRY_DELAY_MS);
+        }
+    }
+    throw lastError;
+};
 /**
  * Client implementation for exchange data access.
  *
@@ -319,7 +443,7 @@ class ClientExchange {
             throw new Error(`ClientExchange unknown time adjust for interval=${interval}`);
         }
         const since = new Date(this.params.execution.context.when.getTime() - adjust * 60 * 1000);
-        const data = await this.params.getCandles(symbol, interval, since, limit);
+        const data = await GET_CANDLES_FN({ symbol, interval, limit }, since, this);
         // Filter candles to strictly match the requested range
         const whenTimestamp = this.params.execution.context.when.getTime();
         const sinceTimestamp = since.getTime();
@@ -357,7 +481,7 @@ class ClientExchange {
         if (endTime > now) {
             return [];
         }
-        const data = await this.params.getCandles(symbol, interval, since, limit);
+        const data = await GET_CANDLES_FN({ symbol, interval, limit }, since, this);
         // Filter candles to strictly match the requested range
         const sinceTimestamp = since.getTime();
         const filteredData = data.filter((candle) => candle.timestamp >= sinceTimestamp && candle.timestamp <= endTime);
@@ -1124,7 +1248,7 @@ class PersistSignalUtils {
      *   async readValue(id) { return JSON.parse(await redis.get(id)); }
      *   async writeValue(id, entity) { await redis.set(id, JSON.stringify(entity)); }
      * }
-     * PersistSignalAdaper.usePersistSignalAdapter(RedisPersist);
+     * PersistSignalAdapter.usePersistSignalAdapter(RedisPersist);
      * ```
      */
     usePersistSignalAdapter(Ctor) {
@@ -1139,16 +1263,16 @@ class PersistSignalUtils {
  * @example
  * ```typescript
  * // Custom adapter
- * PersistSignalAdaper.usePersistSignalAdapter(RedisPersist);
+ * PersistSignalAdapter.usePersistSignalAdapter(RedisPersist);
  *
  * // Read signal
- * const signal = await PersistSignalAdaper.readSignalData("my-strategy", "BTCUSDT");
+ * const signal = await PersistSignalAdapter.readSignalData("my-strategy", "BTCUSDT");
  *
  * // Write signal
- * await PersistSignalAdaper.writeSignalData(signal, "my-strategy", "BTCUSDT");
+ * await PersistSignalAdapter.writeSignalData(signal, "my-strategy", "BTCUSDT");
  * ```
  */
-const PersistSignalAdaper = new PersistSignalUtils();
+const PersistSignalAdapter = new PersistSignalUtils();
 const PERSIST_RISK_UTILS_METHOD_NAME_USE_PERSIST_RISK_ADAPTER = "PersistRiskUtils.usePersistRiskAdapter";
 const PERSIST_RISK_UTILS_METHOD_NAME_READ_DATA = "PersistRiskUtils.readPositionData";
 const PERSIST_RISK_UTILS_METHOD_NAME_WRITE_DATA = "PersistRiskUtils.writePositionData";
@@ -1521,7 +1645,7 @@ const WAIT_FOR_INIT_FN$1 = async (self) => {
     if (self.params.execution.context.backtest) {
         return;
     }
-    const pendingSignal = await PersistSignalAdaper.readSignalData(self.params.strategyName, self.params.execution.context.symbol);
+    const pendingSignal = await PersistSignalAdapter.readSignalData(self.params.strategyName, self.params.execution.context.symbol);
     if (!pendingSignal) {
         return;
     }
@@ -1983,25 +2107,33 @@ const PROCESS_SCHEDULED_SIGNAL_CANDLES_FN = async (self, scheduled, candles) =>
         let shouldActivate = false;
         let shouldCancel = false;
         if (scheduled.position === "long") {
-            // КРИТИЧНО: Сначала проверяем StopLoss (отмена приоритетнее активации)
-            // Отмена если цена упала СЛИШКОМ низко (ниже SL)
+            // КРИТИЧНО для LONG:
+            // - priceOpen > priceStopLoss (по валидации)
+            // - Активация: low <= priceOpen (цена упала до входа)
+            // - Отмена: low <= priceStopLoss (цена пробила SL)
+            //
+            // EDGE CASE: если low <= priceStopLoss И low <= priceOpen на ОДНОЙ свече:
+            // => Отмена имеет ПРИОРИТЕТ! (SL пробит ДО или ВМЕСТЕ с активацией)
+            // Сигнал НЕ открывается, сразу отменяется
             if (candle.low <= scheduled.priceStopLoss) {
                 shouldCancel = true;
             }
-            // Long = покупаем дешевле, ждем падения цены ДО priceOpen
-            // Активируем только если НЕ пробит StopLoss
             else if (candle.low <= scheduled.priceOpen) {
                 shouldActivate = true;
             }
         }
         if (scheduled.position === "short") {
-            // КРИТИЧНО: Сначала проверяем StopLoss (отмена приоритетнее активации)
-            // Отмена если цена выросла СЛИШКОМ высоко (выше SL)
+            // КРИТИЧНО для SHORT:
+            // - priceOpen < priceStopLoss (по валидации)
+            // - Активация: high >= priceOpen (цена выросла до входа)
+            // - Отмена: high >= priceStopLoss (цена пробила SL)
+            //
+            // EDGE CASE: если high >= priceStopLoss И high >= priceOpen на ОДНОЙ свече:
+            // => Отмена имеет ПРИОРИТЕТ! (SL пробит ДО или ВМЕСТЕ с активацией)
+            // Сигнал НЕ открывается, сразу отменяется
             if (candle.high >= scheduled.priceStopLoss) {
                 shouldCancel = true;
             }
-            // Short = продаем дороже, ждем роста цены ДО priceOpen
-            // Активируем только если НЕ пробит StopLoss
             else if (candle.high >= scheduled.priceOpen) {
                 shouldActivate = true;
             }
@@ -2141,10 +2273,15 @@ class ClientStrategy {
             pendingSignal,
         });
         this._pendingSignal = pendingSignal;
+        // КРИТИЧНО: Всегда вызываем коллбек onWrite для тестирования persist storage
+        // даже в backtest режиме, чтобы тесты могли перехватывать вызовы через mock adapter
+        if (this.params.callbacks?.onWrite) {
+            this.params.callbacks.onWrite(this.params.execution.context.symbol, this._pendingSignal, this.params.execution.context.backtest);
+        }
         if (this.params.execution.context.backtest) {
             return;
         }
-        await PersistSignalAdaper.writeSignalData(this._pendingSignal, this.params.strategyName, this.params.execution.context.symbol);
+        await PersistSignalAdapter.writeSignalData(this._pendingSignal, this.params.strategyName, this.params.execution.context.symbol);
     }
     /**
      * Performs a single tick of strategy execution.
@@ -10090,4 +10227,4 @@ PositionSizeUtils.atrBased = async (symbol, accountBalance, priceOpen, atr, cont
 };
 const PositionSize = PositionSizeUtils;
 
-export { Backtest, ExecutionContextService, Heat, Live, MethodContextService, Performance, PersistBase, PersistRiskAdapter, PersistSignalAdaper, PositionSize, Schedule, Walker, addExchange, addFrame, addRisk, addSizing, addStrategy, addWalker, emitters, formatPrice, formatQuantity, getAveragePrice, getCandles, getDate, getMode, backtest as lib, listExchanges, listFrames, listRisks, listSizings, listStrategies, listWalkers, listenDoneBacktest, listenDoneBacktestOnce, listenDoneLive, listenDoneLiveOnce, listenDoneWalker, listenDoneWalkerOnce, listenError, listenPerformance, listenProgress, listenSignal, listenSignalBacktest, listenSignalBacktestOnce, listenSignalLive, listenSignalLiveOnce, listenSignalOnce, listenValidation, listenWalker, listenWalkerComplete, listenWalkerOnce, setConfig, setLogger };
+export { Backtest, ExecutionContextService, Heat, Live, MethodContextService, Performance, PersistBase, PersistRiskAdapter, PersistSignalAdapter, PositionSize, Schedule, Walker, addExchange, addFrame, addRisk, addSizing, addStrategy, addWalker, emitters, formatPrice, formatQuantity, getAveragePrice, getCandles, getDate, getMode, backtest as lib, listExchanges, listFrames, listRisks, listSizings, listStrategies, listWalkers, listenDoneBacktest, listenDoneBacktestOnce, listenDoneLive, listenDoneLiveOnce, listenDoneWalker, listenDoneWalkerOnce, listenError, listenPerformance, listenProgress, listenSignal, listenSignalBacktest, listenSignalBacktestOnce, listenSignalLive, listenSignalLiveOnce, listenSignalOnce, listenValidation, listenWalker, listenWalkerComplete, listenWalkerOnce, setConfig, setLogger };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backtest-kit",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "A TypeScript library for trading system backtest",
   "author": {
     "name": "Petr Tripolsky",

package/types.d.ts

@@ -31,6 +31,44 @@ declare const GLOBAL_CONFIG: {
      * Default: 1440 minutes (1 day)
      */
     CC_MAX_SIGNAL_LIFETIME_MINUTES: number;
+    /**
+     * Number of retries for getCandles function
+     * Default: 3 retries
+     */
+    CC_GET_CANDLES_RETRY_COUNT: number;
+    /**
+     * Delay between retries for getCandles function (in milliseconds)
+     * Default: 5000 ms (5 seconds)
+     */
+    CC_GET_CANDLES_RETRY_DELAY_MS: number;
+    /**
+     * Maximum allowed deviation factor for price anomaly detection.
+     * Price should not be more than this factor lower than reference price.
+     *
+     * Reasoning:
+     * - Incomplete candles from Binance API typically have prices near 0 (e.g., $0.01-1)
+     * - Normal BTC price ranges: $20,000-100,000
+     * - Factor 1000 catches prices below $20-100 when median is $20,000-100,000
+     * - Factor 100 would be too permissive (allows $200 when median is $20,000)
+     * - Factor 10000 might be too strict for low-cap altcoins
+     *
+     * Example: BTC at $50,000 median → threshold $50 (catches $0.01-1 anomalies)
+     */
+    CC_GET_CANDLES_PRICE_ANOMALY_THRESHOLD_FACTOR: number;
+    /**
+     * Minimum number of candles required for reliable median calculation.
+     * Below this threshold, use simple average instead of median.
+     *
+     * Reasoning:
+     * - Each candle provides 4 price points (OHLC)
+     * - 5 candles = 20 price points, sufficient for robust median calculation
+     * - Below 5 candles, single anomaly can heavily skew median
+     * - Statistical rule of thumb: minimum 7-10 data points for median stability
+     * - Average is more stable than median for small datasets (n < 20)
+     *
+     * Example: 3 candles = 12 points (use average), 5 candles = 20 points (use median)
+     */
+    CC_GET_CANDLES_MIN_CANDLES_FOR_MEDIAN: number;
 };
 /**
  * Type for global configuration object.
@@ -608,6 +646,8 @@ interface IStrategyCallbacks {
     onSchedule: (symbol: string, data: IScheduledSignalRow, currentPrice: number, backtest: boolean) => void;
     /** Called when scheduled signal is cancelled without opening position */
     onCancel: (symbol: string, data: IScheduledSignalRow, currentPrice: number, backtest: boolean) => void;
+    /** Called when signal is written to persist storage (for testing) */
+    onWrite: (symbol: string, data: ISignalRow | null, backtest: boolean) => void;
 }
 /**
  * Strategy schema registered via addStrategy().
@@ -3433,7 +3473,7 @@ declare class PersistSignalUtils {
      *   async readValue(id) { return JSON.parse(await redis.get(id)); }
      *   async writeValue(id, entity) { await redis.set(id, JSON.stringify(entity)); }
      * }
-     * PersistSignalAdaper.usePersistSignalAdapter(RedisPersist);
+     * PersistSignalAdapter.usePersistSignalAdapter(RedisPersist);
      * ```
      */
     usePersistSignalAdapter(Ctor: TPersistBaseCtor<StrategyName, SignalData>): void;
@@ -3468,16 +3508,16 @@ declare class PersistSignalUtils {
  * @example
  * ```typescript
  * // Custom adapter
- * PersistSignalAdaper.usePersistSignalAdapter(RedisPersist);
+ * PersistSignalAdapter.usePersistSignalAdapter(RedisPersist);
  *
  * // Read signal
- * const signal = await PersistSignalAdaper.readSignalData("my-strategy", "BTCUSDT");
+ * const signal = await PersistSignalAdapter.readSignalData("my-strategy", "BTCUSDT");
  *
  * // Write signal
- * await PersistSignalAdaper.writeSignalData(signal, "my-strategy", "BTCUSDT");
+ * await PersistSignalAdapter.writeSignalData(signal, "my-strategy", "BTCUSDT");
  * ```
  */
-declare const PersistSignalAdaper: PersistSignalUtils;
+declare const PersistSignalAdapter: PersistSignalUtils;
 /**
  * Type for persisted risk positions data.
  * Stores Map entries as array of [key, value] tuples for JSON serialization.
@@ -6326,4 +6366,4 @@ declare const backtest: {
     loggerService: LoggerService;
 };
 
-export { Backtest, type BacktestStatistics, type CandleInterval, type DoneContract, type EntityId, ExecutionContextService, type FrameInterval, type GlobalConfig, Heat, type ICandleData, type IExchangeSchema, type IFrameSchema, type IHeatmapRow, type IHeatmapStatistics, type IPersistBase, type IPositionSizeATRParams, type IPositionSizeFixedPercentageParams, type IPositionSizeKellyParams, type IRiskActivePosition, type IRiskCheckArgs, type IRiskSchema, type IRiskValidation, type IRiskValidationFn, type IRiskValidationPayload, type IScheduledSignalRow, type ISignalDto, type ISignalRow, type ISizingCalculateParams, type ISizingCalculateParamsATR, type ISizingCalculateParamsFixedPercentage, type ISizingCalculateParamsKelly, type ISizingSchema, type ISizingSchemaATR, type ISizingSchemaFixedPercentage, type ISizingSchemaKelly, type IStrategyPnL, type IStrategySchema, type IStrategyTickResult, type IStrategyTickResultActive, type IStrategyTickResultCancelled, type IStrategyTickResultClosed, type IStrategyTickResultIdle, type IStrategyTickResultOpened, type IStrategyTickResultScheduled, type IWalkerResults, type IWalkerSchema, type IWalkerStrategyResult, Live, type LiveStatistics, MethodContextService, Performance, type PerformanceContract, type PerformanceMetricType, type PerformanceStatistics, PersistBase, PersistRiskAdapter, PersistSignalAdaper, PositionSize, type ProgressContract, type RiskData, Schedule, type ScheduleStatistics, type SignalData, type SignalInterval, type TPersistBase, type TPersistBaseCtor, Walker, type WalkerMetric, type WalkerStatistics, addExchange, addFrame, addRisk, addSizing, addStrategy, addWalker, emitters, formatPrice, formatQuantity, getAveragePrice, getCandles, getDate, getMode, backtest as lib, listExchanges, listFrames, listRisks, listSizings, listStrategies, listWalkers, listenDoneBacktest, listenDoneBacktestOnce, listenDoneLive, listenDoneLiveOnce, listenDoneWalker, listenDoneWalkerOnce, listenError, listenPerformance, listenProgress, listenSignal, listenSignalBacktest, listenSignalBacktestOnce, listenSignalLive, listenSignalLiveOnce, listenSignalOnce, listenValidation, listenWalker, listenWalkerComplete, listenWalkerOnce, setConfig, setLogger };
+export { Backtest, type BacktestStatistics, type CandleInterval, type DoneContract, type EntityId, ExecutionContextService, type FrameInterval, type GlobalConfig, Heat, type ICandleData, type IExchangeSchema, type IFrameSchema, type IHeatmapRow, type IHeatmapStatistics, type IPersistBase, type IPositionSizeATRParams, type IPositionSizeFixedPercentageParams, type IPositionSizeKellyParams, type IRiskActivePosition, type IRiskCheckArgs, type IRiskSchema, type IRiskValidation, type IRiskValidationFn, type IRiskValidationPayload, type IScheduledSignalRow, type ISignalDto, type ISignalRow, type ISizingCalculateParams, type ISizingCalculateParamsATR, type ISizingCalculateParamsFixedPercentage, type ISizingCalculateParamsKelly, type ISizingSchema, type ISizingSchemaATR, type ISizingSchemaFixedPercentage, type ISizingSchemaKelly, type IStrategyPnL, type IStrategySchema, type IStrategyTickResult, type IStrategyTickResultActive, type IStrategyTickResultCancelled, type IStrategyTickResultClosed, type IStrategyTickResultIdle, type IStrategyTickResultOpened, type IStrategyTickResultScheduled, type IWalkerResults, type IWalkerSchema, type IWalkerStrategyResult, Live, type LiveStatistics, MethodContextService, Performance, type PerformanceContract, type PerformanceMetricType, type PerformanceStatistics, PersistBase, PersistRiskAdapter, PersistSignalAdapter, PositionSize, type ProgressContract, type RiskData, Schedule, type ScheduleStatistics, type SignalData, type SignalInterval, type TPersistBase, type TPersistBaseCtor, Walker, type WalkerMetric, type WalkerStatistics, addExchange, addFrame, addRisk, addSizing, addStrategy, addWalker, emitters, formatPrice, formatQuantity, getAveragePrice, getCandles, getDate, getMode, backtest as lib, listExchanges, listFrames, listRisks, listSizings, listStrategies, listWalkers, listenDoneBacktest, listenDoneBacktestOnce, listenDoneLive, listenDoneLiveOnce, listenDoneWalker, listenDoneWalkerOnce, listenError, listenPerformance, listenProgress, listenSignal, listenSignalBacktest, listenSignalBacktestOnce, listenSignalLive, listenSignalLiveOnce, listenSignalOnce, listenValidation, listenWalker, listenWalkerComplete, listenWalkerOnce, setConfig, setLogger };