backtest-kit 3.0.18 → 3.1.1

package/README.md

@@ -441,6 +441,30 @@ Unlike cloud-based platforms, backtest-kit runs entirely in your environment. Yo
 
 The `backtest-kit` ecosystem extends beyond the core library, offering complementary packages and tools to enhance your trading system development experience:
 
+
+### @backtest-kit/cli
+
+> **[Explore on NPM](https://www.npmjs.com/package/@backtest-kit/cli)** 📟
+
+The **@backtest-kit/cli** package is a zero-boilerplate CLI runner for backtest-kit strategies. Point it at your strategy file and run backtests, paper trading, or live bots — no infrastructure code required.
+
+#### Key Features
+- 🚀 **Zero Config**: Run a backtest with one command — no setup code needed
+- 🔄 **Three Modes**: `--backtest`, `--paper`, `--live` with graceful SIGINT shutdown
+- 💾 **Auto Cache**: Warms OHLCV candle cache for all intervals before the backtest starts
+- 🌐 **Web Dashboard**: Launch `@backtest-kit/ui` with a single `--ui` flag
+- 📬 **Telegram Alerts**: Formatted trade notifications with price charts via `--telegram`
+- 🗂️ **Monorepo Ready**: Each strategy's `dump/`, `modules/`, and `template/` are automatically isolated by entry point directory
+
+#### Use Case
+The fastest way to run any backtest-kit strategy from the command line. Instead of writing boilerplate for storage, notifications, candle caching, and signal logging, add one dependency and wire up your `package.json` scripts. Works equally well for a single-strategy project or a monorepo with dozens of strategies in separate subdirectories.
+
+#### Get Started
+```bash
+npx -y @backtest-kit/cli --init
+```
+
+
 ### @backtest-kit/pinets
 
 > **[Explore on NPM](https://www.npmjs.com/package/@backtest-kit/pinets)** 📜
@@ -531,9 +555,32 @@ npm install @backtest-kit/signals backtest-kit
 ```
 
 
+
+### @backtest-kit/graph
+
+> **[Explore on NPM](https://www.npmjs.com/package/@backtest-kit/graph)** 🔗
+
+The **@backtest-kit/graph** package lets you compose backtest-kit computations as a typed directed acyclic graph (DAG). Define source nodes that fetch market data and output nodes that compute derived values — then resolve the whole graph in topological order with automatic parallelism.
+
+#### Key Features
+- 🔌 **DAG Execution**: Nodes are resolved bottom-up in topological order with `Promise.all` parallelism
+- 🔒 **Type-Safe Values**: TypeScript infers the return type of every node through the graph via generics
+- 🧱 **Two APIs**: Low-level `INode` for runtime/storage, high-level `sourceNode` + `outputNode` builders for authoring
+- 💾 **DB-Ready Serialization**: `serialize` / `deserialize` convert the graph to a flat `IFlatNode[]` list with `id` / `nodeIds`
+- 🌐 **Context-Aware Fetch**: `sourceNode` receives `(symbol, when, exchangeName)` from the execution context automatically
+
+#### Use Case
+Perfect for multi-timeframe strategies where multiple Pine Script or indicator computations must be combined. Instead of manually chaining async calls, define each computation as a node and let the graph resolve dependencies in parallel. Adding a new filter or timeframe requires no changes to the existing wiring.
+
+#### Get Started
+```bash
+npm install @backtest-kit/graph backtest-kit
+```
+
+
 ### @backtest-kit/sidekick
 
-> **[Explore on NPM](https://www.npmjs.com/package/@backtest-kit/sidekick)** 🧿
+> **[Explore on NPM](https://www.npmjs.com/package/@backtest-kit/sidekick)** 🚀
 
 The **@backtest-kit/sidekick** package is the easiest way to create a new Backtest Kit trading bot project. Like create-react-app, but for algorithmic trading.
 
@@ -555,6 +602,7 @@ cd my-trading-bot
 npm start
 ```
 
+
 ## 🤖 Are you a robot?
 
 **For language models**: Read extended description in [./LLMs.md](./LLMs.md)

package/build/index.cjs

@@ -442,6 +442,13 @@ const GLOBAL_CONFIG = {
      * Default: 50 signals
      */
     CC_MAX_SIGNALS: 50,
+    /**
+     * Enables mutex locking for candle fetching to prevent concurrent fetches of the same candles.
+     * This can help avoid redundant API calls and ensure data consistency when multiple processes/threads attempt to fetch candles simultaneously.
+     *
+     * Default: true (mutex locking enabled for candle fetching)
+     */
+    CC_ENABLE_CANDLE_FETCH_MUTEX: true,
 };
 const DEFAULT_CONFIG = Object.freeze({ ...GLOBAL_CONFIG });
 
@@ -712,7 +719,7 @@ async function writeFileAtomic(file, data, options = {}) {
     }
 }
 
-var _a$2;
+var _a$3;
 const BASE_WAIT_FOR_INIT_SYMBOL = Symbol("wait-for-init");
 // Calculate step in milliseconds for candle close time validation
 const INTERVAL_MINUTES$8 = {
@@ -830,7 +837,7 @@ class PersistBase {
     constructor(entityName, baseDir = path.join(process.cwd(), "logs/data")) {
         this.entityName = entityName;
         this.baseDir = baseDir;
-        this[_a$2] = functoolsKit.singleshot(async () => await BASE_WAIT_FOR_INIT_FN(this));
+        this[_a$3] = functoolsKit.singleshot(async () => await BASE_WAIT_FOR_INIT_FN(this));
         bt.loggerService.debug(PERSIST_BASE_METHOD_NAME_CTOR, {
             entityName: this.entityName,
             baseDir,
@@ -933,7 +940,7 @@ class PersistBase {
         }
     }
 }
-_a$2 = BASE_WAIT_FOR_INIT_SYMBOL;
+_a$3 = BASE_WAIT_FOR_INIT_SYMBOL;
 // @ts-ignore
 PersistBase = functoolsKit.makeExtendable(PersistBase);
 /**
@@ -1940,6 +1947,69 @@ class PersistNotificationUtils {
  */
 const PersistNotificationAdapter = new PersistNotificationUtils();
 
+var _a$2, _b$2;
+const BUSY_DELAY = 100;
+const SET_BUSY_SYMBOL = Symbol("setBusy");
+const GET_BUSY_SYMBOL = Symbol("getBusy");
+const ACQUIRE_LOCK_SYMBOL = Symbol("acquireLock");
+const RELEASE_LOCK_SYMBOL = Symbol("releaseLock");
+const ACQUIRE_LOCK_FN = async (self) => {
+    while (self[GET_BUSY_SYMBOL]()) {
+        await functoolsKit.sleep(BUSY_DELAY);
+    }
+    self[SET_BUSY_SYMBOL](true);
+};
+class Lock {
+    constructor() {
+        this._isBusy = 0;
+        this[_a$2] = functoolsKit.queued(ACQUIRE_LOCK_FN);
+        this[_b$2] = () => this[SET_BUSY_SYMBOL](false);
+        this.acquireLock = async () => {
+            await this[ACQUIRE_LOCK_SYMBOL](this);
+        };
+        this.releaseLock = async () => {
+            await this[RELEASE_LOCK_SYMBOL]();
+        };
+    }
+    [SET_BUSY_SYMBOL](isBusy) {
+        this._isBusy += isBusy ? 1 : -1;
+        if (this._isBusy < 0) {
+            throw new Error("Extra release in finally block");
+        }
+    }
+    [GET_BUSY_SYMBOL]() {
+        return !!this._isBusy;
+    }
+}
+_a$2 = ACQUIRE_LOCK_SYMBOL, _b$2 = RELEASE_LOCK_SYMBOL;
+
+const METHOD_NAME_ACQUIRE_LOCK = "CandleUtils.acquireLock";
+const METHOD_NAME_RELEASE_LOCK = "CandleUtils.releaseLock";
+class CandleUtils {
+    constructor() {
+        this._lock = new Lock();
+        this.acquireLock = async (source) => {
+            bt.loggerService.info(METHOD_NAME_ACQUIRE_LOCK, {
+                source,
+            });
+            if (!GLOBAL_CONFIG.CC_ENABLE_CANDLE_FETCH_MUTEX) {
+                return;
+            }
+            return await this._lock.acquireLock();
+        };
+        this.releaseLock = async (source) => {
+            bt.loggerService.info(METHOD_NAME_RELEASE_LOCK, {
+                source,
+            });
+            if (!GLOBAL_CONFIG.CC_ENABLE_CANDLE_FETCH_MUTEX) {
+                return;
+            }
+            return await this._lock.releaseLock();
+        };
+    }
+}
+const Candle = new CandleUtils();
+
 const MS_PER_MINUTE$5 = 60000;
 const INTERVAL_MINUTES$7 = {
     "1m": 1,
@@ -2119,34 +2189,40 @@ const GET_CANDLES_FN = async (dto, since, self) => {
     const step = INTERVAL_MINUTES$7[dto.interval];
     const sinceTimestamp = since.getTime();
     const untilTimestamp = sinceTimestamp + dto.limit * step * MS_PER_MINUTE$5;
-    // Try to read from cache first
-    const cachedCandles = await READ_CANDLES_CACHE_FN$1(dto, sinceTimestamp, untilTimestamp, self);
-    if (cachedCandles !== null) {
-        return cachedCandles;
-    }
-    // Cache miss or error - fetch from API
-    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, self.params.execution.context.backtest);
-            VALIDATE_NO_INCOMPLETE_CANDLES_FN(result);
-            // Write to cache after successful fetch
-            await WRITE_CANDLES_CACHE_FN$1(result, dto, self);
-            return result;
+    await Candle.acquireLock(`ClientExchange GET_CANDLES_FN symbol=${dto.symbol} interval=${dto.interval} limit=${dto.limit}`);
+    try {
+        // Try to read from cache first
+        const cachedCandles = await READ_CANDLES_CACHE_FN$1(dto, sinceTimestamp, untilTimestamp, self);
+        if (cachedCandles !== null) {
+            return cachedCandles;
         }
-        catch (err) {
-            const message = `ClientExchange GET_CANDLES_FN: attempt ${i + 1} failed for symbol=${dto.symbol}, interval=${dto.interval}, since=${since.toISOString()}, limit=${dto.limit}}`;
-            const payload = {
-                error: functoolsKit.errorData(err),
-                message: functoolsKit.getErrorMessage(err),
-            };
-            self.params.logger.warn(message, payload);
-            console.warn(message, payload);
-            lastError = err;
-            await functoolsKit.sleep(GLOBAL_CONFIG.CC_GET_CANDLES_RETRY_DELAY_MS);
+        // Cache miss or error - fetch from API
+        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, self.params.execution.context.backtest);
+                VALIDATE_NO_INCOMPLETE_CANDLES_FN(result);
+                // Write to cache after successful fetch
+                await WRITE_CANDLES_CACHE_FN$1(result, dto, self);
+                return result;
+            }
+            catch (err) {
+                const message = `ClientExchange GET_CANDLES_FN: attempt ${i + 1} failed for symbol=${dto.symbol}, interval=${dto.interval}, since=${since.toISOString()}, limit=${dto.limit}}`;
+                const payload = {
+                    error: functoolsKit.errorData(err),
+                    message: functoolsKit.getErrorMessage(err),
+                };
+                self.params.logger.warn(message, payload);
+                console.warn(message, payload);
+                lastError = err;
+                await functoolsKit.sleep(GLOBAL_CONFIG.CC_GET_CANDLES_RETRY_DELAY_MS);
+            }
         }
+        throw lastError;
+    }
+    finally {
+        Candle.releaseLock(`ClientExchange GET_CANDLES_FN symbol=${dto.symbol} interval=${dto.interval} limit=${dto.limit}`);
     }
-    throw lastError;
 };
 /**
  * Wrapper to call onCandleData callback with error handling.
@@ -2829,8 +2905,9 @@ class ExchangeConnectionService {
  *
  * For signals with partial closes:
  * - Calculates weighted PNL: Σ(percent_i × pnl_i) for each partial + (remaining% × final_pnl)
- * - Each partial close has its own fees and slippage
- * - Total fees = 2 × (number of partial closes + 1 final close) × CC_PERCENT_FEE
+ * - Each partial close has its own slippage
+ * - Open fee is charged once; close fees are proportional to each partial's size
+ * - Total fees = CC_PERCENT_FEE (open) + CC_PERCENT_FEE × 1 (closes sum to 100%) = 2 × CC_PERCENT_FEE
  *
  * Formula breakdown:
  * 1. Apply slippage to open/close prices (worse execution)
@@ -2877,7 +2954,8 @@ const toProfitLossDto = (signal, priceClose) => {
     // Calculate weighted PNL with partial closes
     if (signal._partial && signal._partial.length > 0) {
         let totalWeightedPnl = 0;
-        let totalFees = 0;
+        // Open fee is paid once for the whole position
+        let totalFees = GLOBAL_CONFIG.CC_PERCENT_FEE;
         // Calculate PNL for each partial close
         for (const partial of signal._partial) {
             const partialPercent = partial.percent;
@@ -2904,8 +2982,8 @@ const toProfitLossDto = (signal, priceClose) => {
             // Weight by percentage of position closed
             const weightedPnl = (partialPercent / 100) * partialPnl;
             totalWeightedPnl += weightedPnl;
-            // Each partial has fees for open + close (2 transactions)
-            totalFees += GLOBAL_CONFIG.CC_PERCENT_FEE * 2;
+            // Close fee is proportional to the size of this partial
+            totalFees += GLOBAL_CONFIG.CC_PERCENT_FEE * (partialPercent / 100);
         }
         // Calculate PNL for remaining position (if any)
         // Compute totalClosed from _partial array
@@ -2934,10 +3012,11 @@ const toProfitLossDto = (signal, priceClose) => {
             // Weight by remaining percentage
             const weightedRemainingPnl = (remainingPercent / 100) * remainingPnl;
             totalWeightedPnl += weightedRemainingPnl;
-            // Final close also has fees
-            totalFees += GLOBAL_CONFIG.CC_PERCENT_FEE * 2;
+            // Close fee is proportional to the remaining size
+            totalFees += GLOBAL_CONFIG.CC_PERCENT_FEE * (remainingPercent / 100);
         }
         // Subtract total fees from weighted PNL
+        // totalFees = CC_PERCENT_FEE (open) + CC_PERCENT_FEE × 1 (all closes sum to 100%) = 2 × CC_PERCENT_FEE
         const pnlPercentage = totalWeightedPnl - totalFees;
         return {
             pnlPercentage,
@@ -26327,55 +26406,61 @@ class ExchangeInstance {
             const sinceTimestamp = alignedWhen - limit * stepMs;
             const since = new Date(sinceTimestamp);
             const untilTimestamp = alignedWhen;
-            // Try to read from cache first
-            const cachedCandles = await READ_CANDLES_CACHE_FN({ symbol, interval, limit }, sinceTimestamp, untilTimestamp, this.exchangeName);
-            if (cachedCandles !== null) {
-                return cachedCandles;
-            }
-            let allData = [];
-            // If limit exceeds CC_MAX_CANDLES_PER_REQUEST, fetch data in chunks
-            if (limit > GLOBAL_CONFIG.CC_MAX_CANDLES_PER_REQUEST) {
-                let remaining = limit;
-                let currentSince = new Date(since.getTime());
-                const isBacktest = await GET_BACKTEST_FN();
-                while (remaining > 0) {
-                    const chunkLimit = Math.min(remaining, GLOBAL_CONFIG.CC_MAX_CANDLES_PER_REQUEST);
-                    const chunkData = await getCandles(symbol, interval, currentSince, chunkLimit, isBacktest);
-                    allData.push(...chunkData);
-                    remaining -= chunkLimit;
-                    if (remaining > 0) {
-                        // Move currentSince forward by the number of candles fetched
-                        currentSince = new Date(currentSince.getTime() + chunkLimit * stepMs);
+            await Candle.acquireLock(`ExchangeInstance.getCandles symbol=${symbol} interval=${interval} limit=${limit}`);
+            try {
+                // Try to read from cache first
+                const cachedCandles = await READ_CANDLES_CACHE_FN({ symbol, interval, limit }, sinceTimestamp, untilTimestamp, this.exchangeName);
+                if (cachedCandles !== null) {
+                    return cachedCandles;
+                }
+                let allData = [];
+                // If limit exceeds CC_MAX_CANDLES_PER_REQUEST, fetch data in chunks
+                if (limit > GLOBAL_CONFIG.CC_MAX_CANDLES_PER_REQUEST) {
+                    let remaining = limit;
+                    let currentSince = new Date(since.getTime());
+                    const isBacktest = await GET_BACKTEST_FN();
+                    while (remaining > 0) {
+                        const chunkLimit = Math.min(remaining, GLOBAL_CONFIG.CC_MAX_CANDLES_PER_REQUEST);
+                        const chunkData = await getCandles(symbol, interval, currentSince, chunkLimit, isBacktest);
+                        allData.push(...chunkData);
+                        remaining -= chunkLimit;
+                        if (remaining > 0) {
+                            // Move currentSince forward by the number of candles fetched
+                            currentSince = new Date(currentSince.getTime() + chunkLimit * stepMs);
+                        }
                     }
                 }
+                else {
+                    const isBacktest = await GET_BACKTEST_FN();
+                    allData = await getCandles(symbol, interval, since, limit, isBacktest);
+                }
+                // Apply distinct by timestamp to remove duplicates
+                const uniqueData = Array.from(new Map(allData.map((candle) => [candle.timestamp, candle])).values());
+                if (allData.length !== uniqueData.length) {
+                    bt.loggerService.warn(`ExchangeInstance getCandles: Removed ${allData.length - uniqueData.length} duplicate candles by timestamp`);
+                }
+                // Validate adapter returned data
+                if (uniqueData.length === 0) {
+                    throw new Error(`ExchangeInstance getCandles: adapter returned empty array. ` +
+                        `Expected ${limit} candles starting from openTime=${sinceTimestamp}.`);
+                }
+                if (uniqueData[0].timestamp !== sinceTimestamp) {
+                    throw new Error(`ExchangeInstance getCandles: first candle timestamp mismatch. ` +
+                        `Expected openTime=${sinceTimestamp}, got=${uniqueData[0].timestamp}. ` +
+                        `Adapter must return candles with timestamp=openTime, starting from aligned since.`);
+                }
+                if (uniqueData.length !== limit) {
+                    throw new Error(`ExchangeInstance getCandles: candle count mismatch. ` +
+                        `Expected ${limit} candles, got ${uniqueData.length}. ` +
+                        `Adapter must return exact number of candles requested.`);
+                }
+                // Write to cache after successful fetch
+                await WRITE_CANDLES_CACHE_FN(uniqueData, { symbol, interval, limit }, this.exchangeName);
+                return uniqueData;
             }
-            else {
-                const isBacktest = await GET_BACKTEST_FN();
-                allData = await getCandles(symbol, interval, since, limit, isBacktest);
-            }
-            // Apply distinct by timestamp to remove duplicates
-            const uniqueData = Array.from(new Map(allData.map((candle) => [candle.timestamp, candle])).values());
-            if (allData.length !== uniqueData.length) {
-                bt.loggerService.warn(`ExchangeInstance getCandles: Removed ${allData.length - uniqueData.length} duplicate candles by timestamp`);
-            }
-            // Validate adapter returned data
-            if (uniqueData.length === 0) {
-                throw new Error(`ExchangeInstance getCandles: adapter returned empty array. ` +
-                    `Expected ${limit} candles starting from openTime=${sinceTimestamp}.`);
-            }
-            if (uniqueData[0].timestamp !== sinceTimestamp) {
-                throw new Error(`ExchangeInstance getCandles: first candle timestamp mismatch. ` +
-                    `Expected openTime=${sinceTimestamp}, got=${uniqueData[0].timestamp}. ` +
-                    `Adapter must return candles with timestamp=openTime, starting from aligned since.`);
-            }
-            if (uniqueData.length !== limit) {
-                throw new Error(`ExchangeInstance getCandles: candle count mismatch. ` +
-                    `Expected ${limit} candles, got ${uniqueData.length}. ` +
-                    `Adapter must return exact number of candles requested.`);
+            finally {
+                Candle.releaseLock(`ExchangeInstance.getCandles symbol=${symbol} interval=${interval} limit=${limit}`);
             }
-            // Write to cache after successful fetch
-            await WRITE_CANDLES_CACHE_FN(uniqueData, { symbol, interval, limit }, this.exchangeName);
-            return uniqueData;
         };
         /**
          * Calculates VWAP (Volume Weighted Average Price) from last N 1m candles.
@@ -26609,56 +26694,62 @@ class ExchangeInstance {
                     `Provide one of: (sDate+eDate+limit), (sDate+eDate), (eDate+limit), (sDate+limit), or (limit only). ` +
                     `Got: sDate=${sDate}, eDate=${eDate}, limit=${limit}`);
             }
-            // Try to read from cache first
-            const untilTimestamp = sinceTimestamp + calculatedLimit * stepMs;
-            const cachedCandles = await READ_CANDLES_CACHE_FN({ symbol, interval, limit: calculatedLimit }, sinceTimestamp, untilTimestamp, this.exchangeName);
-            if (cachedCandles !== null) {
-                return cachedCandles;
-            }
-            // Fetch candles
-            const since = new Date(sinceTimestamp);
-            let allData = [];
-            const isBacktest = await GET_BACKTEST_FN();
-            const getCandles = this._methods.getCandles;
-            if (calculatedLimit > GLOBAL_CONFIG.CC_MAX_CANDLES_PER_REQUEST) {
-                let remaining = calculatedLimit;
-                let currentSince = new Date(since.getTime());
-                while (remaining > 0) {
-                    const chunkLimit = Math.min(remaining, GLOBAL_CONFIG.CC_MAX_CANDLES_PER_REQUEST);
-                    const chunkData = await getCandles(symbol, interval, currentSince, chunkLimit, isBacktest);
-                    allData.push(...chunkData);
-                    remaining -= chunkLimit;
-                    if (remaining > 0) {
-                        currentSince = new Date(currentSince.getTime() + chunkLimit * stepMs);
+            await Candle.acquireLock(`ExchangeInstance.getRawCandles symbol=${symbol} interval=${interval} limit=${calculatedLimit}`);
+            try {
+                // Try to read from cache first
+                const untilTimestamp = sinceTimestamp + calculatedLimit * stepMs;
+                const cachedCandles = await READ_CANDLES_CACHE_FN({ symbol, interval, limit: calculatedLimit }, sinceTimestamp, untilTimestamp, this.exchangeName);
+                if (cachedCandles !== null) {
+                    return cachedCandles;
+                }
+                // Fetch candles
+                const since = new Date(sinceTimestamp);
+                let allData = [];
+                const isBacktest = await GET_BACKTEST_FN();
+                const getCandles = this._methods.getCandles;
+                if (calculatedLimit > GLOBAL_CONFIG.CC_MAX_CANDLES_PER_REQUEST) {
+                    let remaining = calculatedLimit;
+                    let currentSince = new Date(since.getTime());
+                    while (remaining > 0) {
+                        const chunkLimit = Math.min(remaining, GLOBAL_CONFIG.CC_MAX_CANDLES_PER_REQUEST);
+                        const chunkData = await getCandles(symbol, interval, currentSince, chunkLimit, isBacktest);
+                        allData.push(...chunkData);
+                        remaining -= chunkLimit;
+                        if (remaining > 0) {
+                            currentSince = new Date(currentSince.getTime() + chunkLimit * stepMs);
+                        }
                     }
                 }
+                else {
+                    allData = await getCandles(symbol, interval, since, calculatedLimit, isBacktest);
+                }
+                // Apply distinct by timestamp to remove duplicates
+                const uniqueData = Array.from(new Map(allData.map((candle) => [candle.timestamp, candle])).values());
+                if (allData.length !== uniqueData.length) {
+                    bt.loggerService.warn(`ExchangeInstance getRawCandles: Removed ${allData.length - uniqueData.length} duplicate candles by timestamp`);
+                }
+                // Validate adapter returned data
+                if (uniqueData.length === 0) {
+                    throw new Error(`ExchangeInstance getRawCandles: adapter returned empty array. ` +
+                        `Expected ${calculatedLimit} candles starting from openTime=${sinceTimestamp}.`);
+                }
+                if (uniqueData[0].timestamp !== sinceTimestamp) {
+                    throw new Error(`ExchangeInstance getRawCandles: first candle timestamp mismatch. ` +
+                        `Expected openTime=${sinceTimestamp}, got=${uniqueData[0].timestamp}. ` +
+                        `Adapter must return candles with timestamp=openTime, starting from aligned since.`);
+                }
+                if (uniqueData.length !== calculatedLimit) {
+                    throw new Error(`ExchangeInstance getRawCandles: candle count mismatch. ` +
+                        `Expected ${calculatedLimit} candles, got ${uniqueData.length}. ` +
+                        `Adapter must return exact number of candles requested.`);
+                }
+                // Write to cache after successful fetch
+                await WRITE_CANDLES_CACHE_FN(uniqueData, { symbol, interval, limit: calculatedLimit }, this.exchangeName);
+                return uniqueData;
             }
-            else {
-                allData = await getCandles(symbol, interval, since, calculatedLimit, isBacktest);
-            }
-            // Apply distinct by timestamp to remove duplicates
-            const uniqueData = Array.from(new Map(allData.map((candle) => [candle.timestamp, candle])).values());
-            if (allData.length !== uniqueData.length) {
-                bt.loggerService.warn(`ExchangeInstance getRawCandles: Removed ${allData.length - uniqueData.length} duplicate candles by timestamp`);
-            }
-            // Validate adapter returned data
-            if (uniqueData.length === 0) {
-                throw new Error(`ExchangeInstance getRawCandles: adapter returned empty array. ` +
-                    `Expected ${calculatedLimit} candles starting from openTime=${sinceTimestamp}.`);
-            }
-            if (uniqueData[0].timestamp !== sinceTimestamp) {
-                throw new Error(`ExchangeInstance getRawCandles: first candle timestamp mismatch. ` +
-                    `Expected openTime=${sinceTimestamp}, got=${uniqueData[0].timestamp}. ` +
-                    `Adapter must return candles with timestamp=openTime, starting from aligned since.`);
-            }
-            if (uniqueData.length !== calculatedLimit) {
-                throw new Error(`ExchangeInstance getRawCandles: candle count mismatch. ` +
-                    `Expected ${calculatedLimit} candles, got ${uniqueData.length}. ` +
-                    `Adapter must return exact number of candles requested.`);
+            finally {
+                Candle.releaseLock(`ExchangeInstance.getRawCandles symbol=${symbol} interval=${interval} limit=${calculatedLimit}`);
             }
-            // Write to cache after successful fetch
-            await WRITE_CANDLES_CACHE_FN(uniqueData, { symbol, interval, limit: calculatedLimit }, this.exchangeName);
-            return uniqueData;
         };
         const schema = bt.exchangeSchemaService.get(this.exchangeName);
         this._methods = CREATE_EXCHANGE_INSTANCE_FN(schema);
@@ -30145,6 +30236,115 @@ function listenStrategyCommitOnce(filterFn, fn) {
     return strategyCommitSubject.filter(filterFn).once(fn);
 }
 
+const WARN_KB = 30;
+const DUMP_MESSAGES_METHOD_NAME = "dump.dumpMessages";
+/**
+ * Dumps chat history and result data to markdown files in a structured directory.
+ *
+ * Creates a subfolder named after `resultId` inside `outputDir`.
+ * If the subfolder already exists, the function returns early without overwriting.
+ * Writes:
+ * - `00_system_prompt.md` — system messages and output data summary
+ * - `NN_user_message.md` — each user message as a separate file
+ * - `NN_llm_output.md` — final LLM output data
+ *
+ * Warns via logger if any user message exceeds 30 KB.
+ *
+ * @param resultId - Unique identifier for the result (used as subfolder name)
+ * @param history - Full chat history containing system, user, and assistant messages
+ * @param result - Structured output data to include in the dump
+ * @param outputDir - Base directory for output files (default: `./dump/strategy`)
+ * @returns Promise that resolves when all files are written
+ *
+ * @example
+ * ```typescript
+ * import { dumpMessages } from "backtest-kit";
+ *
+ * await dumpMessages("result-123", history, { profit: 42 });
+ * ```
+ */
+async function dumpMessages(resultId, history, result, outputDir = "./dump/strategy") {
+    bt.loggerService.info(DUMP_MESSAGES_METHOD_NAME, {
+        resultId,
+        outputDir,
+    });
+    // Extract system messages and system reminders from existing data
+    const systemMessages = history.filter((m) => m.role === "system");
+    const userMessages = history.filter((m) => m.role === "user");
+    const subfolderPath = path.join(outputDir, String(resultId));
+    try {
+        await fs.access(subfolderPath);
+        return;
+    }
+    catch {
+        await fs.mkdir(subfolderPath, { recursive: true });
+    }
+    {
+        let summary = "# Outline Result Summary\n";
+        {
+            summary += "\n";
+            summary += `**ResultId**: ${resultId}\n`;
+            summary += "\n";
+        }
+        if (result) {
+            summary += "## Output Data\n\n";
+            summary += "```json\n";
+            summary += JSON.stringify(result, null, 2);
+            summary += "\n```\n\n";
+        }
+        // Add system messages to summary
+        if (systemMessages.length > 0) {
+            summary += "## System Messages\n\n";
+            systemMessages.forEach((msg, idx) => {
+                summary += `### System Message ${idx + 1}\n\n`;
+                summary += msg.content;
+                summary += "\n";
+            });
+        }
+        const summaryFile = path.join(subfolderPath, "00_system_prompt.md");
+        await fs.writeFile(summaryFile, summary, "utf8");
+    }
+    {
+        await Promise.all(Array.from(userMessages.entries()).map(async ([idx, message]) => {
+            const messageNum = String(idx + 1).padStart(2, "0");
+            const contentFileName = `${messageNum}_user_message.md`;
+            const contentFilePath = path.join(subfolderPath, contentFileName);
+            {
+                const messageSizeBytes = Buffer.byteLength(message.content, "utf8");
+                const messageSizeKb = Math.floor(messageSizeBytes / 1024);
+                if (messageSizeKb > WARN_KB) {
+                    console.warn(`User message ${idx + 1} is ${messageSizeBytes} bytes (${messageSizeKb}kb), which exceeds warning limit`);
+                    bt.loggerService.warn(DUMP_MESSAGES_METHOD_NAME, {
+                        resultId,
+                        messageIndex: idx + 1,
+                        messageSizeBytes,
+                        messageSizeKb,
+                    });
+                }
+            }
+            let content = `# User Input ${idx + 1}\n\n`;
+            content += `**ResultId**: ${resultId}\n\n`;
+            content += message.content;
+            content += "\n";
+            await fs.writeFile(contentFilePath, content, "utf8");
+        }));
+    }
+    {
+        const messageNum = String(userMessages.length + 1).padStart(2, "0");
+        const contentFileName = `${messageNum}_llm_output.md`;
+        const contentFilePath = path.join(subfolderPath, contentFileName);
+        let content = "# Full Outline Result\n\n";
+        content += `**ResultId**: ${resultId}\n\n`;
+        if (result) {
+            content += "## Output Data\n\n";
+            content += "```json\n";
+            content += JSON.stringify(result, null, 2);
+            content += "\n```\n";
+        }
+        await fs.writeFile(contentFilePath, content, "utf8");
+    }
+}
+
 const BACKTEST_METHOD_NAME_RUN = "BacktestUtils.run";
 const BACKTEST_METHOD_NAME_BACKGROUND = "BacktestUtils.background";
 const BACKTEST_METHOD_NAME_STOP = "BacktestUtils.stop";
@@ -37458,6 +37658,7 @@ exports.commitPartialLoss = commitPartialLoss;
 exports.commitPartialProfit = commitPartialProfit;
 exports.commitTrailingStop = commitTrailingStop;
 exports.commitTrailingTake = commitTrailingTake;
+exports.dumpMessages = dumpMessages;
 exports.emitters = emitters;
 exports.formatPrice = formatPrice;
 exports.formatQuantity = formatQuantity;