backtest-kit 3.4.0 → 3.4.2

package/build/index.mjs

@@ -408,6 +408,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.
@@ -422,6 +428,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.
@@ -756,6 +770,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;
@@ -1926,6 +1945,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;
@@ -2667,6 +2786,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);
+    }
 }
 
 /**
@@ -2703,6 +2871,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.
  *
@@ -2741,7 +2921,7 @@ class ExchangeConnectionService {
          * @returns Configured ClientExchange instance
          */
         this.getExchange = 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,
@@ -2750,6 +2930,7 @@ class ExchangeConnectionService {
                 formatPrice,
                 formatQuantity,
                 getOrderBook,
+                getAggregatedTrades,
                 callbacks,
             });
         });
@@ -2855,6 +3036,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.
          *
@@ -11228,6 +11425,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.
          *
@@ -26647,6 +26872,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.
@@ -26702,6 +26928,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,
@@ -26747,11 +26985,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,
     };
 };
 /**
@@ -27063,6 +27303,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.
          *
@@ -27332,6 +27624,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.
          *
@@ -27871,6 +28176,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).
  *
@@ -28199,6 +28505,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";
@@ -30862,6 +31203,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 = 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: 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: 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: 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: 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: 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: 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: 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: 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";
@@ -38260,4 +39011,4 @@ const set = (object, path, value) => {
     }
 };
 
-export { ActionBase, Backtest, Breakeven, Cache, Constant, Exchange, ExecutionContextService, Heat, Live, Markdown, MarkdownFileBase, MarkdownFolderBase, MethodContextService, Notification, NotificationBacktest, NotificationLive, Partial, Performance, PersistBase, PersistBreakevenAdapter, PersistCandleAdapter, PersistNotificationAdapter, PersistPartialAdapter, PersistRiskAdapter, PersistScheduleAdapter, PersistSignalAdapter, PersistStorageAdapter, PositionSize, Report, ReportBase, Risk, Schedule, Storage, StorageBacktest, StorageLive, Strategy, Walker, addActionSchema, addExchangeSchema, addFrameSchema, addRiskSchema, addSizingSchema, addStrategySchema, addWalkerSchema, alignToInterval, checkCandles, commitActivateScheduled, commitAverageBuy, commitBreakeven, commitCancelScheduled, commitClosePending, commitPartialLoss, commitPartialProfit, commitTrailingStop, commitTrailingTake, dumpMessages, emitters, formatPrice, formatQuantity, get, getActionSchema, getAveragePrice, getBacktestTimeframe, getCandles, getColumns, getConfig, getContext, getDate, getDefaultColumns, getDefaultConfig, getExchangeSchema, getFrameSchema, getMode, getNextCandles, getOrderBook, getRawCandles, getRiskSchema, getSizingSchema, getStrategySchema, getSymbol, getWalkerSchema, hasTradeContext, backtest as lib, listExchangeSchema, listFrameSchema, listRiskSchema, listSizingSchema, listStrategySchema, listWalkerSchema, listenActivePing, listenActivePingOnce, listenBacktestProgress, listenBreakevenAvailable, listenBreakevenAvailableOnce, listenDoneBacktest, listenDoneBacktestOnce, listenDoneLive, listenDoneLiveOnce, listenDoneWalker, listenDoneWalkerOnce, listenError, listenExit, listenPartialLossAvailable, listenPartialLossAvailableOnce, listenPartialProfitAvailable, listenPartialProfitAvailableOnce, listenPerformance, listenRisk, listenRiskOnce, listenSchedulePing, listenSchedulePingOnce, listenSignal, listenSignalBacktest, listenSignalBacktestOnce, listenSignalLive, listenSignalLiveOnce, listenSignalOnce, listenStrategyCommit, listenStrategyCommitOnce, listenValidation, listenWalker, listenWalkerComplete, listenWalkerOnce, listenWalkerProgress, overrideActionSchema, overrideExchangeSchema, overrideFrameSchema, overrideRiskSchema, overrideSizingSchema, overrideStrategySchema, overrideWalkerSchema, parseArgs, roundTicks, set, setColumns, setConfig, setLogger, stopStrategy, validate, waitForCandle, warmCandles };
+export { ActionBase, Backtest, Breakeven, Cache, Constant, Exchange, ExecutionContextService, Heat, Live, Log, Markdown, MarkdownFileBase, MarkdownFolderBase, MethodContextService, Notification, NotificationBacktest, NotificationLive, Partial, Performance, PersistBase, PersistBreakevenAdapter, PersistCandleAdapter, PersistLogAdapter, PersistNotificationAdapter, PersistPartialAdapter, PersistRiskAdapter, PersistScheduleAdapter, PersistSignalAdapter, PersistStorageAdapter, PositionSize, Report, ReportBase, Risk, Schedule, Storage, StorageBacktest, StorageLive, Strategy, Walker, addActionSchema, addExchangeSchema, addFrameSchema, addRiskSchema, addSizingSchema, addStrategySchema, addWalkerSchema, alignToInterval, checkCandles, commitActivateScheduled, commitAverageBuy, commitBreakeven, commitCancelScheduled, commitClosePending, commitPartialLoss, commitPartialProfit, commitTrailingStop, commitTrailingTake, dumpMessages, emitters, formatPrice, formatQuantity, get, getActionSchema, getAggregatedTrades, getAveragePrice, getBacktestTimeframe, getCandles, getColumns, getConfig, getContext, getDate, getDefaultColumns, getDefaultConfig, getExchangeSchema, getFrameSchema, getMode, getNextCandles, getOrderBook, getRawCandles, getRiskSchema, getSizingSchema, getStrategySchema, getSymbol, getWalkerSchema, hasTradeContext, backtest as lib, listExchangeSchema, listFrameSchema, listRiskSchema, listSizingSchema, listStrategySchema, listWalkerSchema, listenActivePing, listenActivePingOnce, listenBacktestProgress, listenBreakevenAvailable, listenBreakevenAvailableOnce, listenDoneBacktest, listenDoneBacktestOnce, listenDoneLive, listenDoneLiveOnce, listenDoneWalker, listenDoneWalkerOnce, listenError, listenExit, listenPartialLossAvailable, listenPartialLossAvailableOnce, listenPartialProfitAvailable, listenPartialProfitAvailableOnce, listenPerformance, listenRisk, listenRiskOnce, listenSchedulePing, listenSchedulePingOnce, listenSignal, listenSignalBacktest, listenSignalBacktestOnce, listenSignalLive, listenSignalLiveOnce, listenSignalOnce, listenStrategyCommit, listenStrategyCommitOnce, listenValidation, listenWalker, listenWalkerComplete, listenWalkerOnce, listenWalkerProgress, overrideActionSchema, overrideExchangeSchema, overrideFrameSchema, overrideRiskSchema, overrideSizingSchema, overrideStrategySchema, overrideWalkerSchema, parseArgs, roundTicks, set, setColumns, setConfig, setLogger, stopStrategy, validate, waitForCandle, warmCandles };