backtest-kit 3.4.0 → 3.4.2

package/build/index.cjs

@@ -428,6 +428,12 @@ const GLOBAL_CONFIG = {
      * Default: 20 levels
      */
     CC_ORDER_BOOK_MAX_DEPTH_LEVELS: 1000,
+    /**
+     * Maximum minutes of aggregated trades to fetch when no limit is provided.
+     * If limit is not specified, the system will fetch aggregated trades for this many minutes starting from the current time minus the offset.
+     * Binance requirement
+     */
+    CC_AGGREGATED_TRADES_MAX_MINUTES: 60,
     /**
      * Maximum number of notifications to keep in storage.
      * Older notifications are removed when this limit is exceeded.
@@ -442,6 +448,14 @@ const GLOBAL_CONFIG = {
      * Default: 50 signals
      */
     CC_MAX_SIGNALS: 50,
+    /**
+     * Maximum number of log lines to keep in storage.
+     * Older log lines are removed when this limit is exceeded.
+     * This helps prevent unbounded log growth which can consume memory and degrade performance over time.
+     *
+     * Default: 1000 log lines
+     */
+    CC_MAX_LOG_LINES: 1000,
     /**
      * 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.
@@ -776,6 +790,11 @@ const PERSIST_NOTIFICATION_UTILS_METHOD_NAME_WRITE_DATA = "PersistNotificationUt
 const PERSIST_NOTIFICATION_UTILS_METHOD_NAME_USE_JSON = "PersistNotificationUtils.useJson";
 const PERSIST_NOTIFICATION_UTILS_METHOD_NAME_USE_DUMMY = "PersistNotificationUtils.useDummy";
 const PERSIST_NOTIFICATION_UTILS_METHOD_NAME_USE_PERSIST_NOTIFICATION_ADAPTER = "PersistNotificationUtils.usePersistNotificationAdapter";
+const PERSIST_LOG_UTILS_METHOD_NAME_READ_DATA = "PersistLogUtils.readLogData";
+const PERSIST_LOG_UTILS_METHOD_NAME_WRITE_DATA = "PersistLogUtils.writeLogData";
+const PERSIST_LOG_UTILS_METHOD_NAME_USE_JSON = "PersistLogUtils.useJson";
+const PERSIST_LOG_UTILS_METHOD_NAME_USE_DUMMY = "PersistLogUtils.useDummy";
+const PERSIST_LOG_UTILS_METHOD_NAME_USE_PERSIST_LOG_ADAPTER = "PersistLogUtils.usePersistLogAdapter";
 const BASE_WAIT_FOR_INIT_FN_METHOD_NAME = "PersistBase.waitForInitFn";
 const BASE_UNLINK_RETRY_COUNT = 5;
 const BASE_UNLINK_RETRY_DELAY = 1000;
@@ -1946,6 +1965,106 @@ class PersistNotificationUtils {
  * Used by NotificationPersistLiveUtils/NotificationPersistBacktestUtils for notification persistence.
  */
 const PersistNotificationAdapter = new PersistNotificationUtils();
+/**
+ * Utility class for managing log entry persistence.
+ *
+ * Features:
+ * - Memoized storage instance
+ * - Custom adapter support
+ * - Atomic read/write operations for LogData
+ * - Each log entry stored as separate file keyed by id
+ * - Crash-safe log state management
+ *
+ * Used by LogPersistUtils for log entry persistence.
+ */
+class PersistLogUtils {
+    constructor() {
+        this.PersistLogFactory = PersistBase;
+        this._logStorage = null;
+        /**
+         * Reads persisted log entries.
+         *
+         * Called by LogPersistUtils.waitForInit() to restore state.
+         * Uses keys() from PersistBase to iterate over all stored entries.
+         * Returns empty array if no entries exist.
+         *
+         * @returns Promise resolving to array of log entries
+         */
+        this.readLogData = async () => {
+            bt.loggerService.info(PERSIST_LOG_UTILS_METHOD_NAME_READ_DATA);
+            const isInitial = !this._logStorage;
+            const stateStorage = this.getLogStorage();
+            await stateStorage.waitForInit(isInitial);
+            const entries = [];
+            for await (const entryId of stateStorage.keys()) {
+                const entry = await stateStorage.readValue(entryId);
+                entries.push(entry);
+            }
+            return entries;
+        };
+        /**
+         * Writes log entries to disk with atomic file writes.
+         *
+         * Called by LogPersistUtils after each log call to persist state.
+         * Uses entry.id as the storage key for individual file storage.
+         * Uses atomic writes to prevent corruption on crashes.
+         *
+         * @param logData - Log entries to persist
+         * @returns Promise that resolves when write is complete
+         */
+        this.writeLogData = async (logData) => {
+            bt.loggerService.info(PERSIST_LOG_UTILS_METHOD_NAME_WRITE_DATA);
+            const isInitial = !this._logStorage;
+            const stateStorage = this.getLogStorage();
+            await stateStorage.waitForInit(isInitial);
+            for (const entry of logData) {
+                if (await stateStorage.hasValue(entry.id)) {
+                    continue;
+                }
+                await stateStorage.writeValue(entry.id, entry);
+            }
+        };
+    }
+    getLogStorage() {
+        if (!this._logStorage) {
+            this._logStorage = Reflect.construct(this.PersistLogFactory, [
+                `log`,
+                `./dump/data/log/`,
+            ]);
+        }
+        return this._logStorage;
+    }
+    /**
+     * Registers a custom persistence adapter.
+     *
+     * @param Ctor - Custom PersistBase constructor
+     */
+    usePersistLogAdapter(Ctor) {
+        bt.loggerService.info(PERSIST_LOG_UTILS_METHOD_NAME_USE_PERSIST_LOG_ADAPTER);
+        this.PersistLogFactory = Ctor;
+    }
+    /**
+     * Switches to the default JSON persist adapter.
+     * All future persistence writes will use JSON storage.
+     */
+    useJson() {
+        bt.loggerService.log(PERSIST_LOG_UTILS_METHOD_NAME_USE_JSON);
+        this.usePersistLogAdapter(PersistBase);
+    }
+    /**
+     * Switches to a dummy persist adapter that discards all writes.
+     * All future persistence writes will be no-ops.
+     */
+    useDummy() {
+        bt.loggerService.log(PERSIST_LOG_UTILS_METHOD_NAME_USE_DUMMY);
+        this.usePersistLogAdapter(PersistDummy);
+    }
+}
+/**
+ * Global singleton instance of PersistLogUtils.
+ * Used by LogPersistUtils for log entry persistence.
+ */
+const PersistLogAdapter = new PersistLogUtils();
 
 var _a$2, _b$2;
 const BUSY_DELAY = 100;
@@ -2687,6 +2806,55 @@ class ClientExchange {
             GLOBAL_CONFIG.CC_ORDER_BOOK_TIME_OFFSET_MINUTES * MS_PER_MINUTE$5);
         return await this.params.getOrderBook(symbol, depth, from, to, this.params.execution.context.backtest);
     }
+    /**
+     * Fetches aggregated trades backwards from execution context time.
+     *
+     * Algorithm:
+     * 1. Align when down to the nearest minute boundary (1-minute granularity)
+     * 2. If limit is not specified: fetch one window of CC_AGGREGATED_TRADES_MAX_MINUTES
+     * 3. If limit is specified: paginate backwards in CC_AGGREGATED_TRADES_MAX_MINUTES
+     *    chunks until at least limit trades are collected, then slice to limit
+     *
+     * Look-ahead bias prevention:
+     * - `to` is always aligned down to the minute (never exceeds current when)
+     * - Each pagination window goes strictly backwards from alignedWhen
+     *
+     * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+     * @param limit - Optional maximum number of trades to return. If not specified,
+     *                returns all trades within the last CC_AGGREGATED_TRADES_MAX_MINUTES window.
+     * @returns Promise resolving to array of aggregated trade data
+     */
+    async getAggregatedTrades(symbol, limit) {
+        this.params.logger.debug("ClientExchange getAggregatedTrades", {
+            symbol,
+            limit,
+        });
+        const whenTimestamp = this.params.execution.context.when.getTime();
+        // Align to 1-minute boundary to prevent look-ahead bias
+        const alignedTo = ALIGN_TO_INTERVAL_FN$2(whenTimestamp, 1);
+        const windowMs = GLOBAL_CONFIG.CC_AGGREGATED_TRADES_MAX_MINUTES * MS_PER_MINUTE$5 - MS_PER_MINUTE$5;
+        // No limit: fetch a single window and return as-is
+        if (limit === undefined) {
+            const to = new Date(alignedTo);
+            const from = new Date(alignedTo - windowMs);
+            return await this.params.getAggregatedTrades(symbol, from, to, this.params.execution.context.backtest);
+        }
+        // With limit: paginate backwards until we have enough trades
+        const result = [];
+        let windowEnd = alignedTo;
+        while (result.length < limit) {
+            const windowStart = windowEnd - windowMs;
+            const to = new Date(windowEnd);
+            const from = new Date(windowStart);
+            const chunk = await this.params.getAggregatedTrades(symbol, from, to, this.params.execution.context.backtest);
+            // Prepend chunk (older data goes first)
+            result.unshift(...chunk);
+            // Move window backwards
+            windowEnd = windowStart;
+        }
+        // Slice to requested limit (most recent trades)
+        return result.slice(-limit);
+    }
 }
 
 /**
@@ -2723,6 +2891,18 @@ const DEFAULT_FORMAT_PRICE_FN$1 = async (_symbol, price, _backtest) => {
 const DEFAULT_GET_ORDER_BOOK_FN$1 = async (_symbol, _depth, _from, _to, _backtest) => {
     throw new Error(`getOrderBook is not implemented for this exchange`);
 };
+/**
+ * Default implementation for getAggregatedTrades.
+ * Throws an error indicating the method is not implemented.
+ *
+ * @param _symbol - Trading pair symbol (unused)
+ * @param _from - Start of time range (unused - can be ignored in live implementations)
+ * @param _to - End of time range (unused - can be ignored in live implementations)
+ * @param _backtest - Whether running in backtest mode (unused)
+ */
+const DEFAULT_GET_AGGREGATED_TRADES_FN$1 = async (_symbol, _from, _to, _backtest) => {
+    throw new Error(`getAggregatedTrades is not implemented for this exchange`);
+};
 /**
  * Connection service routing exchange operations to correct ClientExchange instance.
  *
@@ -2761,7 +2941,7 @@ class ExchangeConnectionService {
          * @returns Configured ClientExchange instance
          */
         this.getExchange = functoolsKit.memoize(([exchangeName]) => `${exchangeName}`, (exchangeName) => {
-            const { getCandles = DEFAULT_GET_CANDLES_FN$1, formatPrice = DEFAULT_FORMAT_PRICE_FN$1, formatQuantity = DEFAULT_FORMAT_QUANTITY_FN$1, getOrderBook = DEFAULT_GET_ORDER_BOOK_FN$1, callbacks } = this.exchangeSchemaService.get(exchangeName);
+            const { getCandles = DEFAULT_GET_CANDLES_FN$1, formatPrice = DEFAULT_FORMAT_PRICE_FN$1, formatQuantity = DEFAULT_FORMAT_QUANTITY_FN$1, getOrderBook = DEFAULT_GET_ORDER_BOOK_FN$1, getAggregatedTrades = DEFAULT_GET_AGGREGATED_TRADES_FN$1, callbacks } = this.exchangeSchemaService.get(exchangeName);
             return new ClientExchange({
                 execution: this.executionContextService,
                 logger: this.loggerService,
@@ -2770,6 +2950,7 @@ class ExchangeConnectionService {
                 formatPrice,
                 formatQuantity,
                 getOrderBook,
+                getAggregatedTrades,
                 callbacks,
             });
         });
@@ -2875,6 +3056,22 @@ class ExchangeConnectionService {
             });
             return await this.getExchange(this.methodContextService.context.exchangeName).getOrderBook(symbol, depth);
         };
+        /**
+         * Fetches aggregated trades for a trading pair using configured exchange.
+         *
+         * Routes to exchange determined by methodContextService.context.exchangeName.
+         *
+         * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+         * @param limit - Optional maximum number of trades to fetch. If empty returns one window of data.
+         * @returns Promise resolving to array of aggregated trade data
+         */
+        this.getAggregatedTrades = async (symbol, limit) => {
+            this.loggerService.log("exchangeConnectionService getAggregatedTrades", {
+                symbol,
+                limit,
+            });
+            return await this.getExchange(this.methodContextService.context.exchangeName).getAggregatedTrades(symbol, limit);
+        };
         /**
          * Fetches raw candles with flexible date/limit parameters.
          *
@@ -11248,6 +11445,34 @@ class ExchangeCoreService {
                 backtest,
             });
         };
+        /**
+         * Fetches aggregated trades with execution context.
+         *
+         * @param symbol - Trading pair symbol
+         * @param when - Timestamp for context (used in backtest mode)
+         * @param backtest - Whether running in backtest mode
+         * @param limit - Optional maximum number of trades to fetch
+         * @returns Promise resolving to array of aggregated trade data
+         */
+        this.getAggregatedTrades = async (symbol, when, backtest, limit) => {
+            this.loggerService.log("exchangeCoreService getAggregatedTrades", {
+                symbol,
+                when,
+                backtest,
+                limit,
+            });
+            if (!MethodContextService.hasContext()) {
+                throw new Error("exchangeCoreService getAggregatedTrades requires a method context");
+            }
+            await this.validate(this.methodContextService.context.exchangeName);
+            return await ExecutionContextService.runInContext(async () => {
+                return await this.exchangeConnectionService.getAggregatedTrades(symbol, limit);
+            }, {
+                symbol,
+                when,
+                backtest,
+            });
+        };
         /**
          * Fetches raw candles with flexible date/limit parameters and execution context.
          *
@@ -26667,6 +26892,7 @@ const EXCHANGE_METHOD_NAME_FORMAT_QUANTITY = "ExchangeUtils.formatQuantity";
 const EXCHANGE_METHOD_NAME_FORMAT_PRICE = "ExchangeUtils.formatPrice";
 const EXCHANGE_METHOD_NAME_GET_ORDER_BOOK = "ExchangeUtils.getOrderBook";
 const EXCHANGE_METHOD_NAME_GET_RAW_CANDLES = "ExchangeUtils.getRawCandles";
+const EXCHANGE_METHOD_NAME_GET_AGGREGATED_TRADES = "ExchangeUtils.getAggregatedTrades";
 const MS_PER_MINUTE$3 = 60000;
 /**
  * Gets current timestamp from execution context if available.
@@ -26722,6 +26948,18 @@ const DEFAULT_FORMAT_PRICE_FN = async (_symbol, price, _backtest) => {
 const DEFAULT_GET_ORDER_BOOK_FN = async (_symbol, _depth, _from, _to, _backtest) => {
     throw new Error(`getOrderBook is not implemented for this exchange`);
 };
+/**
+ * Default implementation for getAggregatedTrades.
+ * Throws an error indicating the method is not implemented.
+ *
+ * @param _symbol - Trading pair symbol (unused)
+ * @param _from - Start of time range (unused - can be ignored in live implementations)
+ * @param _to - End of time range (unused - can be ignored in live implementations)
+ * @param _backtest - Whether running in backtest mode (unused)
+ */
+const DEFAULT_GET_AGGREGATED_TRADES_FN = async (_symbol, _from, _to, _backtest) => {
+    throw new Error(`getAggregatedTrades is not implemented for this exchange`);
+};
 const INTERVAL_MINUTES$3 = {
     "1m": 1,
     "3m": 3,
@@ -26767,11 +27005,13 @@ const CREATE_EXCHANGE_INSTANCE_FN = (schema) => {
     const formatQuantity = schema.formatQuantity ?? DEFAULT_FORMAT_QUANTITY_FN;
     const formatPrice = schema.formatPrice ?? DEFAULT_FORMAT_PRICE_FN;
     const getOrderBook = schema.getOrderBook ?? DEFAULT_GET_ORDER_BOOK_FN;
+    const getAggregatedTrades = schema.getAggregatedTrades ?? DEFAULT_GET_AGGREGATED_TRADES_FN;
     return {
         getCandles,
         formatQuantity,
         formatPrice,
         getOrderBook,
+        getAggregatedTrades,
     };
 };
 /**
@@ -27083,6 +27323,58 @@ class ExchangeInstance {
             const isBacktest = await GET_BACKTEST_FN();
             return await this._methods.getOrderBook(symbol, depth, from, to, isBacktest);
         };
+        /**
+         * Fetch aggregated trades for a trading pair.
+         *
+         * Calculates time range backwards from current timestamp (or execution context when).
+         * Aligns `to` to 1-minute boundary to prevent look-ahead bias.
+         * If limit is not specified, returns all trades within one CC_AGGREGATED_TRADES_MAX_MINUTES window.
+         * If limit is specified, paginates backwards until at least limit trades are collected.
+         *
+         * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+         * @param limit - Optional maximum number of trades to return
+         * @returns Promise resolving to array of aggregated trade data
+         *
+         * @example
+         * ```typescript
+         * const instance = new ExchangeInstance("binance");
+         * const trades = await instance.getAggregatedTrades("BTCUSDT");
+         * const lastN = await instance.getAggregatedTrades("BTCUSDT", 500);
+         * ```
+         */
+        this.getAggregatedTrades = async (symbol, limit) => {
+            bt.loggerService.info(EXCHANGE_METHOD_NAME_GET_AGGREGATED_TRADES, {
+                exchangeName: this.exchangeName,
+                symbol,
+                limit,
+            });
+            const when = await GET_TIMESTAMP_FN();
+            // Align to 1-minute boundary to prevent look-ahead bias
+            const alignedTo = ALIGN_TO_INTERVAL_FN$1(when.getTime(), 1);
+            const windowMs = GLOBAL_CONFIG.CC_AGGREGATED_TRADES_MAX_MINUTES * MS_PER_MINUTE$3 - MS_PER_MINUTE$3;
+            const isBacktest = await GET_BACKTEST_FN();
+            // No limit: fetch a single window and return as-is
+            if (limit === undefined) {
+                const to = new Date(alignedTo);
+                const from = new Date(alignedTo - windowMs);
+                return await this._methods.getAggregatedTrades(symbol, from, to, isBacktest);
+            }
+            // With limit: paginate backwards until we have enough trades
+            const result = [];
+            let windowEnd = alignedTo;
+            while (result.length < limit) {
+                const windowStart = windowEnd - windowMs;
+                const to = new Date(windowEnd);
+                const from = new Date(windowStart);
+                const chunk = await this._methods.getAggregatedTrades(symbol, from, to, isBacktest);
+                // Prepend chunk (older data goes first)
+                result.unshift(...chunk);
+                // Move window backwards
+                windowEnd = windowStart;
+            }
+            // Slice to requested limit (most recent trades)
+            return result.slice(-limit);
+        };
         /**
          * Fetches raw candles with flexible date/limit parameters.
          *
@@ -27352,6 +27644,19 @@ class ExchangeUtils {
             const instance = this._getInstance(context.exchangeName);
             return await instance.getOrderBook(symbol, depth);
         };
+        /**
+         * Fetch aggregated trades for a trading pair.
+         *
+         * @param symbol - Trading pair symbol
+         * @param context - Execution context with exchange name
+         * @param limit - Optional maximum number of trades to return
+         * @returns Promise resolving to array of aggregated trade data
+         */
+        this.getAggregatedTrades = async (symbol, context, limit) => {
+            bt.exchangeValidationService.validate(context.exchangeName, EXCHANGE_METHOD_NAME_GET_AGGREGATED_TRADES);
+            const instance = this._getInstance(context.exchangeName);
+            return await instance.getAggregatedTrades(symbol, limit);
+        };
         /**
          * Fetches raw candles with flexible date/limit parameters.
          *
@@ -27891,6 +28196,7 @@ const HAS_TRADE_CONTEXT_METHOD_NAME = "exchange.hasTradeContext";
 const GET_ORDER_BOOK_METHOD_NAME = "exchange.getOrderBook";
 const GET_RAW_CANDLES_METHOD_NAME = "exchange.getRawCandles";
 const GET_NEXT_CANDLES_METHOD_NAME = "exchange.getNextCandles";
+const GET_AGGREGATED_TRADES_METHOD_NAME = "exchange.getAggregatedTrades";
 /**
  * Checks if trade context is active (execution and method contexts).
  *
@@ -28219,6 +28525,41 @@ async function getNextCandles(symbol, interval, limit) {
     }
     return await bt.exchangeConnectionService.getNextCandles(symbol, interval, limit);
 }
+/**
+ * Fetches aggregated trades for a trading pair from the registered exchange.
+ *
+ * Trades are fetched backwards from the current execution context time.
+ * If limit is not specified, returns all trades within one CC_AGGREGATED_TRADES_MAX_MINUTES window.
+ * If limit is specified, paginates backwards until at least limit trades are collected.
+ *
+ * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+ * @param limit - Optional maximum number of trades to fetch
+ * @returns Promise resolving to array of aggregated trade data
+ * @throws Error if execution or method context is missing
+ *
+ * @example
+ * ```typescript
+ * // Fetch last hour of trades
+ * const trades = await getAggregatedTrades("BTCUSDT");
+ *
+ * // Fetch last 500 trades
+ * const lastTrades = await getAggregatedTrades("BTCUSDT", 500);
+ * console.log(lastTrades[0]); // { id, price, qty, timestamp, isBuyerMaker }
+ * ```
+ */
+async function getAggregatedTrades(symbol, limit) {
+    bt.loggerService.info(GET_AGGREGATED_TRADES_METHOD_NAME, {
+        symbol,
+        limit,
+    });
+    if (!ExecutionContextService.hasContext()) {
+        throw new Error("getAggregatedTrades requires an execution context");
+    }
+    if (!MethodContextService.hasContext()) {
+        throw new Error("getAggregatedTrades requires a method context");
+    }
+    return await bt.exchangeConnectionService.getAggregatedTrades(symbol, limit);
+}
 
 const CANCEL_SCHEDULED_METHOD_NAME = "strategy.commitCancelScheduled";
 const CLOSE_PENDING_METHOD_NAME = "strategy.commitClosePending";
@@ -30882,6 +31223,416 @@ async function dumpMessages(resultId, history, result, outputDir = "./dump/strat
     }
 }
 
+const LOG_PERSIST_METHOD_NAME_WAIT_FOR_INIT = "LogPersistUtils.waitForInit";
+const LOG_PERSIST_METHOD_NAME_LOG = "LogPersistUtils.log";
+const LOG_PERSIST_METHOD_NAME_DEBUG = "LogPersistUtils.debug";
+const LOG_PERSIST_METHOD_NAME_INFO = "LogPersistUtils.info";
+const LOG_PERSIST_METHOD_NAME_WARN = "LogPersistUtils.warn";
+const LOG_PERSIST_METHOD_NAME_GET_LIST = "LogPersistUtils.getList";
+const LOG_MEMORY_METHOD_NAME_LOG = "LogMemoryUtils.log";
+const LOG_MEMORY_METHOD_NAME_DEBUG = "LogMemoryUtils.debug";
+const LOG_MEMORY_METHOD_NAME_INFO = "LogMemoryUtils.info";
+const LOG_MEMORY_METHOD_NAME_WARN = "LogMemoryUtils.warn";
+const LOG_MEMORY_METHOD_NAME_GET_LIST = "LogMemoryUtils.getList";
+const LOG_ADAPTER_METHOD_NAME_USE_LOGGER = "LogAdapter.useLogger";
+const LOG_ADAPTER_METHOD_NAME_USE_PERSIST = "LogAdapter.usePersist";
+const LOG_ADAPTER_METHOD_NAME_USE_MEMORY = "LogAdapter.useMemory";
+const LOG_ADAPTER_METHOD_NAME_USE_DUMMY = "LogAdapter.useDummy";
+/**
+ * Backtest execution time retrieval function.
+ * Returns the 'when' timestamp from the execution context if available, otherwise returns the current time.
+ * This allows log entries to be timestamped according to the backtest timeline rather than real-world time, improving log relevance and user experience during backtest analysis.
+ */
+const GET_DATE_FN = async () => {
+    if (ExecutionContextService.hasContext()) {
+        return new Date(bt.executionContextService.context.when);
+    }
+    return new Date();
+};
+/**
+ * Persistent log adapter.
+ *
+ * Features:
+ * - Persists log entries to disk using PersistLogAdapter
+ * - Lazy initialization with singleshot pattern
+ * - Maintains up to CC_MAX_LOG_LINES most recent entries
+ * - Each entry stored individually keyed by its id
+ *
+ * Use this adapter (default) for log persistence across sessions.
+ */
+class LogPersistUtils {
+    constructor() {
+        /** Array of log entries */
+        this._entries = [];
+        /**
+         * Singleshot initialization function that loads entries from disk.
+         * Protected by singleshot to ensure one-time execution.
+         */
+        this.waitForInit = functoolsKit.singleshot(async () => {
+            bt.loggerService.info(LOG_PERSIST_METHOD_NAME_WAIT_FOR_INIT);
+            const list = await PersistLogAdapter.readLogData();
+            list.sort((a, b) => a.timestamp - b.timestamp);
+            this._entries = list.slice(-GLOBAL_CONFIG.CC_MAX_LOG_LINES);
+        });
+        /**
+         * Logs a general-purpose message.
+         * Persists entry to disk after appending.
+         * @param topic - The log topic / method name
+         * @param args - Additional arguments
+         */
+        this.log = async (topic, ...args) => {
+            bt.loggerService.info(LOG_PERSIST_METHOD_NAME_LOG, { topic });
+            await this.waitForInit();
+            const date = await GET_DATE_FN();
+            this._entries.push({
+                id: functoolsKit.randomString(),
+                type: "log",
+                timestamp: Date.now(),
+                createdAt: date.toISOString(),
+                topic,
+                args,
+            });
+            this._enforceLimit();
+            await PersistLogAdapter.writeLogData(this._entries);
+        };
+        /**
+         * Logs a debug-level message.
+         * Persists entry to disk after appending.
+         * @param topic - The log topic / method name
+         * @param args - Additional arguments
+         */
+        this.debug = async (topic, ...args) => {
+            bt.loggerService.info(LOG_PERSIST_METHOD_NAME_DEBUG, { topic });
+            await this.waitForInit();
+            const date = await GET_DATE_FN();
+            this._entries.push({
+                id: functoolsKit.randomString(),
+                type: "debug",
+                timestamp: Date.now(),
+                createdAt: date.toISOString(),
+                topic,
+                args,
+            });
+            this._enforceLimit();
+            await PersistLogAdapter.writeLogData(this._entries);
+        };
+        /**
+         * Logs an info-level message.
+         * Persists entry to disk after appending.
+         * @param topic - The log topic / method name
+         * @param args - Additional arguments
+         */
+        this.info = async (topic, ...args) => {
+            bt.loggerService.info(LOG_PERSIST_METHOD_NAME_INFO, { topic });
+            await this.waitForInit();
+            const date = await GET_DATE_FN();
+            this._entries.push({
+                id: functoolsKit.randomString(),
+                type: "info",
+                timestamp: Date.now(),
+                createdAt: date.toISOString(),
+                topic,
+                args,
+            });
+            this._enforceLimit();
+            await PersistLogAdapter.writeLogData(this._entries);
+        };
+        /**
+         * Logs a warning-level message.
+         * Persists entry to disk after appending.
+         * @param topic - The log topic / method name
+         * @param args - Additional arguments
+         */
+        this.warn = async (topic, ...args) => {
+            bt.loggerService.info(LOG_PERSIST_METHOD_NAME_WARN, { topic });
+            await this.waitForInit();
+            const date = await GET_DATE_FN();
+            this._entries.push({
+                id: functoolsKit.randomString(),
+                type: "warn",
+                timestamp: Date.now(),
+                createdAt: date.toISOString(),
+                topic,
+                args,
+            });
+            this._enforceLimit();
+            await PersistLogAdapter.writeLogData(this._entries);
+        };
+        /**
+         * Lists all stored log entries.
+         * @returns Array of all log entries
+         */
+        this.getList = async () => {
+            bt.loggerService.info(LOG_PERSIST_METHOD_NAME_GET_LIST);
+            await this.waitForInit();
+            return [...this._entries];
+        };
+    }
+    /**
+     * Removes oldest entries if limit is exceeded.
+     */
+    _enforceLimit() {
+        if (this._entries.length > GLOBAL_CONFIG.CC_MAX_LOG_LINES) {
+            this._entries.splice(0, this._entries.length - GLOBAL_CONFIG.CC_MAX_LOG_LINES);
+        }
+    }
+}
+/**
+ * In-memory log adapter.
+ *
+ * Features:
+ * - Stores log entries in memory only (no persistence)
+ * - Maintains up to CC_MAX_LOG_LINES most recent entries
+ * - Data is lost when application restarts
+ * - Handles all log levels (log, debug, info, warn)
+ *
+ * Use this adapter for testing or when persistence is not required.
+ */
+class LogMemoryUtils {
+    constructor() {
+        /** Array of log entries */
+        this._entries = [];
+        /**
+         * Logs a general-purpose message.
+         * Appends entry to in-memory array.
+         * @param topic - The log topic / method name
+         * @param args - Additional arguments
+         */
+        this.log = async (topic, ...args) => {
+            bt.loggerService.info(LOG_MEMORY_METHOD_NAME_LOG, { topic });
+            const date = await GET_DATE_FN();
+            this._entries.push({
+                id: functoolsKit.randomString(),
+                type: "log",
+                timestamp: Date.now(),
+                createdAt: date.toISOString(),
+                topic,
+                args,
+            });
+            this._enforceLimit();
+        };
+        /**
+         * Logs a debug-level message.
+         * Appends entry to in-memory array.
+         * @param topic - The log topic / method name
+         * @param args - Additional arguments
+         */
+        this.debug = async (topic, ...args) => {
+            bt.loggerService.info(LOG_MEMORY_METHOD_NAME_DEBUG, { topic });
+            const date = await GET_DATE_FN();
+            this._entries.push({
+                id: functoolsKit.randomString(),
+                type: "debug",
+                timestamp: Date.now(),
+                createdAt: date.toISOString(),
+                topic,
+                args,
+            });
+            this._enforceLimit();
+        };
+        /**
+         * Logs an info-level message.
+         * Appends entry to in-memory array.
+         * @param topic - The log topic / method name
+         * @param args - Additional arguments
+         */
+        this.info = async (topic, ...args) => {
+            bt.loggerService.info(LOG_MEMORY_METHOD_NAME_INFO, { topic });
+            const date = await GET_DATE_FN();
+            this._entries.push({
+                id: functoolsKit.randomString(),
+                type: "info",
+                timestamp: Date.now(),
+                createdAt: date.toISOString(),
+                topic,
+                args,
+            });
+            this._enforceLimit();
+        };
+        /**
+         * Logs a warning-level message.
+         * Appends entry to in-memory array.
+         * @param topic - The log topic / method name
+         * @param args - Additional arguments
+         */
+        this.warn = async (topic, ...args) => {
+            bt.loggerService.info(LOG_MEMORY_METHOD_NAME_WARN, { topic });
+            const date = await GET_DATE_FN();
+            this._entries.push({
+                id: functoolsKit.randomString(),
+                type: "warn",
+                timestamp: Date.now(),
+                createdAt: date.toISOString(),
+                topic,
+                args,
+            });
+            this._enforceLimit();
+        };
+        /**
+         * Lists all stored log entries.
+         * @returns Array of all log entries
+         */
+        this.getList = async () => {
+            bt.loggerService.info(LOG_MEMORY_METHOD_NAME_GET_LIST);
+            return [...this._entries];
+        };
+    }
+    /**
+     * Removes oldest entries if limit is exceeded.
+     */
+    _enforceLimit() {
+        if (this._entries.length > GLOBAL_CONFIG.CC_MAX_LOG_LINES) {
+            this._entries.splice(0, this._entries.length - GLOBAL_CONFIG.CC_MAX_LOG_LINES);
+        }
+    }
+}
+/**
+ * Dummy log adapter that discards all writes.
+ *
+ * Features:
+ * - No-op implementation for all methods
+ * - getList always returns empty array
+ *
+ * Use this adapter to disable log storage completely.
+ */
+class LogDummyUtils {
+    /**
+     * Always returns empty array (no storage).
+     * @returns Empty array
+     */
+    async getList() {
+        return [];
+    }
+    /**
+     * No-op handler for general-purpose log.
+     */
+    log() {
+    }
+    /**
+     * No-op handler for debug-level log.
+     */
+    debug() {
+    }
+    /**
+     * No-op handler for info-level log.
+     */
+    info() {
+    }
+    /**
+     * No-op handler for warning-level log.
+     */
+    warn() {
+    }
+}
+/**
+ * Log adapter with pluggable storage backend.
+ *
+ * Features:
+ * - Adapter pattern for swappable log implementations
+ * - Default adapter: LogMemoryUtils (in-memory storage)
+ * - Alternative adapters: LogPersistUtils, LogDummyUtils
+ * - Convenience methods: usePersist(), useMemory(), useDummy()
+ */
+class LogAdapter {
+    constructor() {
+        /** Internal log utils instance */
+        this._log = new LogMemoryUtils();
+        /**
+         * Lists all stored log entries.
+         * Proxies call to the underlying log adapter.
+         * @returns Array of all log entries
+         */
+        this.getList = async () => {
+            if (this._log.getList) {
+                return await this._log.getList();
+            }
+            return [];
+        };
+        /**
+         * Logs a general-purpose message.
+         * Proxies call to the underlying log adapter.
+         * @param topic - The log topic / method name
+         * @param args - Additional arguments
+         */
+        this.log = (topic, ...args) => {
+            if (this._log.log) {
+                this._log.log(topic, ...args);
+            }
+        };
+        /**
+         * Logs a debug-level message.
+         * Proxies call to the underlying log adapter.
+         * @param topic - The log topic / method name
+         * @param args - Additional arguments
+         */
+        this.debug = (topic, ...args) => {
+            if (this._log.debug) {
+                this._log.debug(topic, ...args);
+            }
+        };
+        /**
+         * Logs an info-level message.
+         * Proxies call to the underlying log adapter.
+         * @param topic - The log topic / method name
+         * @param args - Additional arguments
+         */
+        this.info = (topic, ...args) => {
+            if (this._log.info) {
+                this._log.info(topic, ...args);
+            }
+        };
+        /**
+         * Logs a warning-level message.
+         * Proxies call to the underlying log adapter.
+         * @param topic - The log topic / method name
+         * @param args - Additional arguments
+         */
+        this.warn = (topic, ...args) => {
+            if (this._log.warn) {
+                this._log.warn(topic, ...args);
+            }
+        };
+        /**
+         * Sets the log adapter constructor.
+         * All future log operations will use this adapter.
+         * @param Ctor - Constructor for log adapter
+         */
+        this.useLogger = (Ctor) => {
+            bt.loggerService.info(LOG_ADAPTER_METHOD_NAME_USE_LOGGER);
+            this._log = Reflect.construct(Ctor, []);
+        };
+        /**
+         * Switches to persistent log adapter.
+         * Log entries will be persisted to disk.
+         */
+        this.usePersist = () => {
+            bt.loggerService.info(LOG_ADAPTER_METHOD_NAME_USE_PERSIST);
+            this._log = new LogPersistUtils();
+        };
+        /**
+         * Switches to in-memory log adapter (default).
+         * Log entries will be stored in memory only.
+         */
+        this.useMemory = () => {
+            bt.loggerService.info(LOG_ADAPTER_METHOD_NAME_USE_MEMORY);
+            this._log = new LogMemoryUtils();
+        };
+        /**
+         * Switches to dummy log adapter.
+         * All future log writes will be no-ops.
+         */
+        this.useDummy = () => {
+            bt.loggerService.info(LOG_ADAPTER_METHOD_NAME_USE_DUMMY);
+            this._log = new LogDummyUtils();
+        };
+    }
+}
+/**
+ * Global singleton instance of LogAdapter.
+ * Provides unified log management with pluggable backends.
+ */
+const Log = new LogAdapter();
+
 const BACKTEST_METHOD_NAME_RUN = "BacktestUtils.run";
 const BACKTEST_METHOD_NAME_BACKGROUND = "BacktestUtils.background";
 const BACKTEST_METHOD_NAME_STOP = "BacktestUtils.stop";
@@ -38289,6 +39040,7 @@ exports.Exchange = Exchange;
 exports.ExecutionContextService = ExecutionContextService;
 exports.Heat = Heat;
 exports.Live = Live;
+exports.Log = Log;
 exports.Markdown = Markdown;
 exports.MarkdownFileBase = MarkdownFileBase;
 exports.MarkdownFolderBase = MarkdownFolderBase;
@@ -38301,6 +39053,7 @@ exports.Performance = Performance;
 exports.PersistBase = PersistBase;
 exports.PersistBreakevenAdapter = PersistBreakevenAdapter;
 exports.PersistCandleAdapter = PersistCandleAdapter;
+exports.PersistLogAdapter = PersistLogAdapter;
 exports.PersistNotificationAdapter = PersistNotificationAdapter;
 exports.PersistPartialAdapter = PersistPartialAdapter;
 exports.PersistRiskAdapter = PersistRiskAdapter;
@@ -38341,6 +39094,7 @@ exports.formatPrice = formatPrice;
 exports.formatQuantity = formatQuantity;
 exports.get = get;
 exports.getActionSchema = getActionSchema;
+exports.getAggregatedTrades = getAggregatedTrades;
 exports.getAveragePrice = getAveragePrice;
 exports.getBacktestTimeframe = getBacktestTimeframe;
 exports.getCandles = getCandles;