backtest-kit 1.0.4 → 1.1.0

package/build/index.mjs

@@ -1,14 +1,33 @@
 import { createActivator } from 'di-kit';
 import { scoped } from 'di-scoped';
-import { memoize, makeExtendable, singleshot, getErrorMessage, not, trycatch, retry, randomString, ToolRegistry, sleep, singlerun } from 'functools-kit';
-import fs from 'fs/promises';
+import { memoize, makeExtendable, singleshot, getErrorMessage, not, trycatch, retry, randomString, Subject, ToolRegistry, sleep, str, queued } from 'functools-kit';
+import fs, { mkdir, writeFile } from 'fs/promises';
 import path, { join } from 'path';
 import crypto from 'crypto';
 import os from 'os';
-import Table from 'cli-table3';
 
 const { init, inject, provide } = createActivator("backtest");
 
+/**
+ * Scoped service for method context propagation.
+ *
+ * Uses di-scoped for implicit context passing without explicit parameters.
+ * Context includes strategyName, exchangeName, and frameName.
+ *
+ * Used by PublicServices to inject schema names into ConnectionServices.
+ *
+ * @example
+ * ```typescript
+ * MethodContextService.runAsyncIterator(
+ *   backtestGenerator,
+ *   {
+ *     strategyName: "my-strategy",
+ *     exchangeName: "my-exchange",
+ *     frameName: "1d-backtest"
+ *   }
+ * );
+ * ```
+ */
 const MethodContextService = scoped(class {
     constructor(context) {
         this.context = context;
@@ -47,6 +66,15 @@ const logicPublicServices$1 = {
     backtestLogicPublicService: Symbol('backtestLogicPublicService'),
     liveLogicPublicService: Symbol('liveLogicPublicService'),
 };
+const markdownServices$1 = {
+    backtestMarkdownService: Symbol('backtestMarkdownService'),
+    liveMarkdownService: Symbol('liveMarkdownService'),
+};
+const validationServices$1 = {
+    exchangeValidationService: Symbol('exchangeValidationService'),
+    strategyValidationService: Symbol('strategyValidationService'),
+    frameValidationService: Symbol('frameValidationService'),
+};
 const TYPES = {
     ...baseServices$1,
     ...contextServices$1,
@@ -55,14 +83,39 @@ const TYPES = {
     ...globalServices$1,
     ...logicPrivateServices$1,
     ...logicPublicServices$1,
+    ...markdownServices$1,
+    ...validationServices$1,
 };
 
+/**
+ * Scoped service for execution context propagation.
+ *
+ * Uses di-scoped for implicit context passing without explicit parameters.
+ * Context includes symbol, when (timestamp), and backtest flag.
+ *
+ * Used by GlobalServices to inject context into operations.
+ *
+ * @example
+ * ```typescript
+ * ExecutionContextService.runInContext(
+ *   async () => {
+ *     // Inside this callback, context is automatically available
+ *     return await someOperation();
+ *   },
+ *   { symbol: "BTCUSDT", when: new Date(), backtest: true }
+ * );
+ * ```
+ */
 const ExecutionContextService = scoped(class {
     constructor(context) {
         this.context = context;
     }
 });
 
+/**
+ * No-op logger implementation used as default.
+ * Silently discards all log messages.
+ */
 const NOOP_LOGGER = {
     log() {
     },
@@ -70,31 +123,84 @@ const NOOP_LOGGER = {
     },
     info() {
     },
+    warn() {
+    },
 };
+/**
+ * Logger service with automatic context injection.
+ *
+ * Features:
+ * - Delegates to user-provided logger via setLogger()
+ * - Automatically appends method context (strategyName, exchangeName, frameName)
+ * - Automatically appends execution context (symbol, when, backtest)
+ * - Defaults to NOOP_LOGGER if no logger configured
+ *
+ * Used throughout the framework for consistent logging with context.
+ */
 class LoggerService {
     constructor() {
         this.methodContextService = inject(TYPES.methodContextService);
         this.executionContextService = inject(TYPES.executionContextService);
         this._commonLogger = NOOP_LOGGER;
+        /**
+         * Logs general-purpose message with automatic context injection.
+         *
+         * @param topic - Log topic/category
+         * @param args - Additional log arguments
+         */
         this.log = async (topic, ...args) => {
             await this._commonLogger.log(topic, ...args, this.methodContext, this.executionContext);
         };
+        /**
+         * Logs debug-level message with automatic context injection.
+         *
+         * @param topic - Log topic/category
+         * @param args - Additional log arguments
+         */
         this.debug = async (topic, ...args) => {
             await this._commonLogger.debug(topic, ...args, this.methodContext, this.executionContext);
         };
+        /**
+         * Logs info-level message with automatic context injection.
+         *
+         * @param topic - Log topic/category
+         * @param args - Additional log arguments
+         */
         this.info = async (topic, ...args) => {
             await this._commonLogger.info(topic, ...args, this.methodContext, this.executionContext);
         };
+        /**
+         * Logs warning-level message with automatic context injection.
+         *
+         * @param topic - Log topic/category
+         * @param args - Additional log arguments
+         */
+        this.warn = async (topic, ...args) => {
+            await this._commonLogger.warn(topic, ...args, this.methodContext, this.executionContext);
+        };
+        /**
+         * Sets custom logger implementation.
+         *
+         * @param logger - Custom logger implementing ILogger interface
+         */
         this.setLogger = (logger) => {
             this._commonLogger = logger;
         };
     }
+    /**
+     * Gets current method context if available.
+     * Contains strategyName, exchangeName, frameName from MethodContextService.
+     */
     get methodContext() {
         if (MethodContextService.hasContext()) {
             return this.methodContextService.context;
         }
         return {};
     }
+    /**
+     * Gets current execution context if available.
+     * Contains symbol, when, backtest from ExecutionContextService.
+     */
     get executionContext() {
         if (ExecutionContextService.hasContext()) {
             return this.executionContextService.context;
@@ -115,10 +221,44 @@ const INTERVAL_MINUTES$2 = {
     "6h": 360,
     "8h": 480,
 };
+/**
+ * Client implementation for exchange data access.
+ *
+ * Features:
+ * - Historical candle fetching (backwards from execution context)
+ * - Future candle fetching (forwards for backtest)
+ * - VWAP calculation from last 5 1m candles
+ * - Price/quantity formatting for exchange
+ *
+ * All methods use prototype functions for memory efficiency.
+ *
+ * @example
+ * ```typescript
+ * const exchange = new ClientExchange({
+ *   exchangeName: "binance",
+ *   getCandles: async (symbol, interval, since, limit) => [...],
+ *   formatPrice: async (symbol, price) => price.toFixed(2),
+ *   formatQuantity: async (symbol, quantity) => quantity.toFixed(8),
+ *   execution: executionService,
+ *   logger: loggerService,
+ * });
+ *
+ * const candles = await exchange.getCandles("BTCUSDT", "1m", 100);
+ * const vwap = await exchange.getAveragePrice("BTCUSDT");
+ * ```
+ */
 class ClientExchange {
     constructor(params) {
         this.params = params;
     }
+    /**
+     * Fetches historical candles backwards from execution context time.
+     *
+     * @param symbol - Trading pair symbol
+     * @param interval - Candle interval
+     * @param limit - Number of candles to fetch
+     * @returns Promise resolving to array of candles
+     */
     async getCandles(symbol, interval, limit) {
         this.params.logger.debug(`ClientExchange getCandles`, {
             symbol,
@@ -126,17 +266,34 @@ class ClientExchange {
             limit,
         });
         const step = INTERVAL_MINUTES$2[interval];
-        const adjust = step * limit - 1;
+        const adjust = step * limit - step;
         if (!adjust) {
             throw new Error(`ClientExchange unknown time adjust for interval=${interval}`);
         }
         const since = new Date(this.params.execution.context.when.getTime() - adjust * 60 * 1000);
         const data = await this.params.getCandles(symbol, interval, since, limit);
+        // Filter candles to strictly match the requested range
+        const whenTimestamp = this.params.execution.context.when.getTime();
+        const sinceTimestamp = since.getTime();
+        const filteredData = data.filter((candle) => candle.timestamp >= sinceTimestamp && candle.timestamp <= whenTimestamp);
+        if (filteredData.length < limit) {
+            this.params.logger.warn(`ClientExchange Expected ${limit} candles, got ${filteredData.length}`);
+        }
         if (this.params.callbacks?.onCandleData) {
-            this.params.callbacks.onCandleData(symbol, interval, since, limit, data);
+            this.params.callbacks.onCandleData(symbol, interval, since, limit, filteredData);
         }
-        return data;
+        return filteredData;
     }
+    /**
+     * Fetches future candles forwards from execution context time.
+     * Used in backtest mode to get candles for signal duration.
+     *
+     * @param symbol - Trading pair symbol
+     * @param interval - Candle interval
+     * @param limit - Number of candles to fetch
+     * @returns Promise resolving to array of candles
+     * @throws Error if trying to fetch future candles in live mode
+     */
     async getNextCandles(symbol, interval, limit) {
         this.params.logger.debug(`ClientExchange getNextCandles`, {
             symbol,
@@ -153,11 +310,30 @@ class ClientExchange {
             return [];
         }
         const data = await this.params.getCandles(symbol, interval, since, limit);
+        // Filter candles to strictly match the requested range
+        const sinceTimestamp = since.getTime();
+        const filteredData = data.filter((candle) => candle.timestamp >= sinceTimestamp && candle.timestamp <= endTime);
+        if (filteredData.length < limit) {
+            this.params.logger.warn(`ClientExchange getNextCandles: Expected ${limit} candles, got ${filteredData.length}`);
+        }
         if (this.params.callbacks?.onCandleData) {
-            this.params.callbacks.onCandleData(symbol, interval, since, limit, data);
+            this.params.callbacks.onCandleData(symbol, interval, since, limit, filteredData);
         }
-        return data;
+        return filteredData;
     }
+    /**
+     * Calculates VWAP (Volume Weighted Average Price) from last 5 1m candles.
+     *
+     * Formula:
+     * - Typical Price = (high + low + close) / 3
+     * - VWAP = sum(typical_price * volume) / sum(volume)
+     *
+     * If volume is zero, returns simple average of close prices.
+     *
+     * @param symbol - Trading pair symbol
+     * @returns Promise resolving to VWAP price
+     * @throws Error if no candles available
+     */
     async getAveragePrice(symbol) {
         this.params.logger.debug(`ClientExchange getAveragePrice`, {
             symbol,
@@ -197,13 +373,44 @@ class ClientExchange {
     }
 }
 
+/**
+ * Connection service routing exchange operations to correct ClientExchange instance.
+ *
+ * Routes all IExchange method calls to the appropriate exchange implementation
+ * based on methodContextService.context.exchangeName. Uses memoization to cache
+ * ClientExchange instances for performance.
+ *
+ * Key features:
+ * - Automatic exchange routing via method context
+ * - Memoized ClientExchange instances by exchangeName
+ * - Implements full IExchange interface
+ * - Logging for all operations
+ *
+ * @example
+ * ```typescript
+ * // Used internally by framework
+ * const candles = await exchangeConnectionService.getCandles(
+ *   "BTCUSDT", "1h", 100
+ * );
+ * // Automatically routes to correct exchange based on methodContext
+ * ```
+ */
 class ExchangeConnectionService {
     constructor() {
         this.loggerService = inject(TYPES.loggerService);
         this.executionContextService = inject(TYPES.executionContextService);
         this.exchangeSchemaService = inject(TYPES.exchangeSchemaService);
         this.methodContextService = inject(TYPES.methodContextService);
-        this.getExchange = memoize((exchangeName) => `${exchangeName}`, (exchangeName) => {
+        /**
+         * Retrieves memoized ClientExchange instance for given exchange name.
+         *
+         * Creates ClientExchange on first call, returns cached instance on subsequent calls.
+         * Cache key is exchangeName string.
+         *
+         * @param exchangeName - Name of registered exchange schema
+         * @returns Configured ClientExchange instance
+         */
+        this.getExchange = memoize(([exchangeName]) => `${exchangeName}`, (exchangeName) => {
             const { getCandles, formatPrice, formatQuantity, callbacks } = this.exchangeSchemaService.get(exchangeName);
             return new ClientExchange({
                 execution: this.executionContextService,
@@ -215,6 +422,16 @@ class ExchangeConnectionService {
                 callbacks,
             });
         });
+        /**
+         * Fetches historical candles for symbol using configured exchange.
+         *
+         * Routes to exchange determined by methodContextService.context.exchangeName.
+         *
+         * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+         * @param interval - Candle interval (e.g., "1h", "1d")
+         * @param limit - Maximum number of candles to fetch
+         * @returns Promise resolving to array of candle data
+         */
         this.getCandles = async (symbol, interval, limit) => {
             this.loggerService.log("exchangeConnectionService getCandles", {
                 symbol,
@@ -223,6 +440,17 @@ class ExchangeConnectionService {
             });
             return await this.getExchange(this.methodContextService.context.exchangeName).getCandles(symbol, interval, limit);
         };
+        /**
+         * Fetches next batch of candles relative to executionContext.when.
+         *
+         * Returns candles that come after the current execution timestamp.
+         * Used for backtest progression and live trading updates.
+         *
+         * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+         * @param interval - Candle interval (e.g., "1h", "1d")
+         * @param limit - Maximum number of candles to fetch
+         * @returns Promise resolving to array of candle data
+         */
         this.getNextCandles = async (symbol, interval, limit) => {
             this.loggerService.log("exchangeConnectionService getNextCandles", {
                 symbol,
@@ -231,12 +459,30 @@ class ExchangeConnectionService {
             });
             return await this.getExchange(this.methodContextService.context.exchangeName).getNextCandles(symbol, interval, limit);
         };
+        /**
+         * Retrieves current average price for symbol.
+         *
+         * In live mode: fetches real-time average price from exchange API.
+         * In backtest mode: calculates VWAP from candles in current timeframe.
+         *
+         * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+         * @returns Promise resolving to average price
+         */
         this.getAveragePrice = async (symbol) => {
             this.loggerService.log("exchangeConnectionService getAveragePrice", {
                 symbol,
             });
             return await this.getExchange(this.methodContextService.context.exchangeName).getAveragePrice(symbol);
         };
+        /**
+         * Formats price according to exchange-specific precision rules.
+         *
+         * Ensures price meets exchange requirements for decimal places and tick size.
+         *
+         * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+         * @param price - Raw price value to format
+         * @returns Promise resolving to formatted price string
+         */
         this.formatPrice = async (symbol, price) => {
             this.loggerService.log("exchangeConnectionService getAveragePrice", {
                 symbol,
@@ -244,6 +490,15 @@ class ExchangeConnectionService {
             });
             return await this.getExchange(this.methodContextService.context.exchangeName).formatPrice(symbol, price);
         };
+        /**
+         * Formats quantity according to exchange-specific precision rules.
+         *
+         * Ensures quantity meets exchange requirements for decimal places and lot size.
+         *
+         * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+         * @param quantity - Raw quantity value to format
+         * @returns Promise resolving to formatted quantity string
+         */
         this.formatQuantity = async (symbol, quantity) => {
             this.loggerService.log("exchangeConnectionService getAveragePrice", {
                 symbol,
@@ -254,8 +509,45 @@ class ExchangeConnectionService {
     }
 }
 
+/**
+ * Slippage percentage applied to entry and exit prices.
+ * Simulates market impact and order book depth.
+ */
 const PERCENT_SLIPPAGE = 0.1;
+/**
+ * Fee percentage charged per transaction.
+ * Applied twice (entry and exit) for total fee calculation.
+ */
 const PERCENT_FEE = 0.1;
+/**
+ * Calculates profit/loss for a closed signal with slippage and fees.
+ *
+ * Formula breakdown:
+ * 1. Apply slippage to open/close prices (worse execution)
+ *    - LONG: buy higher (+slippage), sell lower (-slippage)
+ *    - SHORT: sell lower (-slippage), buy higher (+slippage)
+ * 2. Calculate raw PNL percentage
+ *    - LONG: ((closePrice - openPrice) / openPrice) * 100
+ *    - SHORT: ((openPrice - closePrice) / openPrice) * 100
+ * 3. Subtract total fees (0.1% * 2 = 0.2%)
+ *
+ * @param signal - Closed signal with position details
+ * @param priceClose - Actual close price at exit
+ * @returns PNL data with percentage and prices
+ *
+ * @example
+ * ```typescript
+ * const pnl = toProfitLossDto(
+ *   {
+ *     position: "long",
+ *     priceOpen: 50000,
+ *     // ... other signal fields
+ *   },
+ *   51000 // close price
+ * );
+ * console.log(pnl.pnlPercentage); // e.g., 1.8% (after slippage and fees)
+ * ```
+ */
 const toProfitLossDto = (signal, priceClose) => {
     const priceOpen = signal.priceOpen;
     let priceOpenWithSlippage;
@@ -431,9 +723,9 @@ const BASE_WAIT_FOR_INIT_FN = async (self) => {
         }
         catch {
             const filePath = self._getFilePath(key);
-            console.error(`agent-swarm PersistBase found invalid document for filePath=${filePath} entityName=${self.entityName}`);
+            console.error(`backtest-kit PersistBase found invalid document for filePath=${filePath} entityName=${self.entityName}`);
             if (await not(BASE_WAIT_FOR_INIT_UNLINK_FN(filePath))) {
-                console.error(`agent-swarm PersistBase failed to remove invalid document for filePath=${filePath} entityName=${self.entityName}`);
+                console.error(`backtest-kit PersistBase failed to remove invalid document for filePath=${filePath} entityName=${self.entityName}`);
             }
         }
     }
@@ -444,13 +736,36 @@ const BASE_WAIT_FOR_INIT_UNLINK_FN = async (filePath) => trycatch(retry(async ()
         return true;
     }
     catch (error) {
-        console.error(`agent-swarm PersistBase unlink failed for filePath=${filePath} error=${getErrorMessage(error)}`);
+        console.error(`backtest-kit PersistBase unlink failed for filePath=${filePath} error=${getErrorMessage(error)}`);
         throw error;
     }
 }, BASE_UNLINK_RETRY_COUNT, BASE_UNLINK_RETRY_DELAY), {
     defaultValue: false,
 });
+/**
+ * Base class for file-based persistence with atomic writes.
+ *
+ * Features:
+ * - Atomic file writes using writeFileAtomic
+ * - Auto-validation and cleanup of corrupted files
+ * - Async generator support for iteration
+ * - Retry logic for file deletion
+ *
+ * @example
+ * ```typescript
+ * const persist = new PersistBase("my-entity", "./data");
+ * await persist.waitForInit(true);
+ * await persist.writeValue("key1", { data: "value" });
+ * const value = await persist.readValue("key1");
+ * ```
+ */
 const PersistBase = makeExtendable(class {
+    /**
+     * Creates new persistence instance.
+     *
+     * @param entityName - Unique entity type identifier
+     * @param baseDir - Base directory for all entities (default: ./logs/data)
+     */
     constructor(entityName, baseDir = join(process.cwd(), "logs/data")) {
         this.entityName = entityName;
         this.baseDir = baseDir;
@@ -461,6 +776,12 @@ const PersistBase = makeExtendable(class {
         });
         this._directory = join(this.baseDir, this.entityName);
     }
+    /**
+     * Computes file path for entity ID.
+     *
+     * @param entityId - Entity identifier
+     * @returns Full file path to entity JSON file
+     */
     _getFilePath(entityId) {
         return join(this.baseDir, this.entityName, `${entityId}.json`);
     }
@@ -471,6 +792,11 @@ const PersistBase = makeExtendable(class {
         });
         await this[BASE_WAIT_FOR_INIT_SYMBOL]();
     }
+    /**
+     * Returns count of persisted entities.
+     *
+     * @returns Promise resolving to number of .json files in directory
+     */
     async getCount() {
         const files = await fs.readdir(this._directory);
         const { length } = files.filter((file) => file.endsWith(".json"));
@@ -524,6 +850,13 @@ const PersistBase = makeExtendable(class {
             throw new Error(`Failed to write entity ${this.entityName}:${entityId}: ${getErrorMessage(error)}`);
         }
     }
+    /**
+     * Removes entity from storage.
+     *
+     * @param entityId - Entity identifier to remove
+     * @returns Promise that resolves when entity is deleted
+     * @throws Error if entity not found or deletion fails
+     */
     async removeValue(entityId) {
         backtest$1.loggerService.debug(PERSIST_BASE_METHOD_NAME_REMOVE_VALUE, {
             entityName: this.entityName,
@@ -540,6 +873,12 @@ const PersistBase = makeExtendable(class {
             throw new Error(`Failed to remove entity ${this.entityName}:${entityId}: ${getErrorMessage(error)}`);
         }
     }
+    /**
+     * Removes all entities from storage.
+     *
+     * @returns Promise that resolves when all entities are deleted
+     * @throws Error if deletion fails
+     */
     async removeAll() {
         backtest$1.loggerService.debug(PERSIST_BASE_METHOD_NAME_REMOVE_ALL, {
             entityName: this.entityName,
@@ -555,6 +894,13 @@ const PersistBase = makeExtendable(class {
             throw new Error(`Failed to remove values for ${this.entityName}: ${getErrorMessage(error)}`);
         }
     }
+    /**
+     * Async generator yielding all entity values.
+     * Sorted alphanumerically by entity ID.
+     *
+     * @returns AsyncGenerator yielding entities
+     * @throws Error if reading fails
+     */
     async *values() {
         backtest$1.loggerService.debug(PERSIST_BASE_METHOD_NAME_VALUES, {
             entityName: this.entityName,
@@ -577,6 +923,13 @@ const PersistBase = makeExtendable(class {
             throw new Error(`Failed to read values for ${this.entityName}: ${getErrorMessage(error)}`);
         }
     }
+    /**
+     * Async generator yielding all entity IDs.
+     * Sorted alphanumerically.
+     *
+     * @returns AsyncGenerator yielding entity IDs
+     * @throws Error if reading fails
+     */
     async *keys() {
         backtest$1.loggerService.debug(PERSIST_BASE_METHOD_NAME_KEYS, {
             entityName: this.entityName,
@@ -598,11 +951,23 @@ const PersistBase = makeExtendable(class {
             throw new Error(`Failed to read keys for ${this.entityName}: ${getErrorMessage(error)}`);
         }
     }
+    /**
+     * Async iterator implementation.
+     * Delegates to values() generator.
+     *
+     * @returns AsyncIterableIterator yielding entities
+     */
     async *[(_a = BASE_WAIT_FOR_INIT_SYMBOL, Symbol.asyncIterator)]() {
         for await (const entity of this.values()) {
             yield entity;
         }
     }
+    /**
+     * Filters entities by predicate function.
+     *
+     * @param predicate - Filter function
+     * @returns AsyncGenerator yielding filtered entities
+     */
     async *filter(predicate) {
         for await (const entity of this.values()) {
             if (predicate(entity)) {
@@ -610,6 +975,13 @@ const PersistBase = makeExtendable(class {
             }
         }
     }
+    /**
+     * Takes first N entities, optionally filtered.
+     *
+     * @param total - Maximum number of entities to yield
+     * @param predicate - Optional filter function
+     * @returns AsyncGenerator yielding up to total entities
+     */
     async *take(total, predicate) {
         let count = 0;
         if (predicate) {
@@ -635,6 +1007,17 @@ const PersistBase = makeExtendable(class {
         }
     }
 });
+/**
+ * Utility class for managing signal persistence.
+ *
+ * Features:
+ * - Memoized storage instances per strategy
+ * - Custom adapter support
+ * - Atomic read/write operations
+ * - Crash-safe signal state management
+ *
+ * Used by ClientStrategy for live mode persistence.
+ */
 class PersistSignalUtils {
     constructor() {
         this.PersistSignalFactory = PersistBase;
@@ -642,6 +1025,16 @@ class PersistSignalUtils {
             strategyName,
             `./logs/data/signal/`,
         ]));
+        /**
+         * Reads persisted signal data for a strategy and symbol.
+         *
+         * Called by ClientStrategy.waitForInit() to restore state.
+         * Returns null if no signal exists.
+         *
+         * @param strategyName - Strategy identifier
+         * @param symbol - Trading pair symbol
+         * @returns Promise resolving to signal or null
+         */
         this.readSignalData = async (strategyName, symbol) => {
             backtest$1.loggerService.info(PERSIST_SIGNAL_UTILS_METHOD_NAME_READ_DATA);
             const isInitial = !this.getSignalStorage.has(strategyName);
@@ -653,6 +1046,17 @@ class PersistSignalUtils {
             }
             return null;
         };
+        /**
+         * Writes signal data to disk with atomic file writes.
+         *
+         * Called by ClientStrategy.setPendingSignal() to persist state.
+         * Uses atomic writes to prevent corruption on crashes.
+         *
+         * @param signalRow - Signal data (null to clear)
+         * @param strategyName - Strategy identifier
+         * @param symbol - Trading pair symbol
+         * @returns Promise that resolves when write is complete
+         */
         this.writeSignalData = async (signalRow, strategyName, symbol) => {
             backtest$1.loggerService.info(PERSIST_SIGNAL_UTILS_METHOD_NAME_WRITE_DATA);
             const isInitial = !this.getSignalStorage.has(strategyName);
@@ -661,11 +1065,41 @@ class PersistSignalUtils {
             await stateStorage.writeValue(symbol, { signalRow });
         };
     }
+    /**
+     * Registers a custom persistence adapter.
+     *
+     * @param Ctor - Custom PersistBase constructor
+     *
+     * @example
+     * ```typescript
+     * class RedisPersist extends PersistBase {
+     *   async readValue(id) { return JSON.parse(await redis.get(id)); }
+     *   async writeValue(id, entity) { await redis.set(id, JSON.stringify(entity)); }
+     * }
+     * PersistSignalAdaper.usePersistSignalAdapter(RedisPersist);
+     * ```
+     */
     usePersistSignalAdapter(Ctor) {
         backtest$1.loggerService.info(PERSIST_SIGNAL_UTILS_METHOD_NAME_USE_PERSIST_SIGNAL_ADAPTER);
         this.PersistSignalFactory = Ctor;
     }
 }
+/**
+ * Global singleton instance of PersistSignalUtils.
+ * Used by ClientStrategy for signal persistence.
+ *
+ * @example
+ * ```typescript
+ * // Custom adapter
+ * PersistSignalAdaper.usePersistSignalAdapter(RedisPersist);
+ *
+ * // Read signal
+ * const signal = await PersistSignalAdaper.readSignalData("my-strategy", "BTCUSDT");
+ *
+ * // Write signal
+ * await PersistSignalAdaper.writeSignalData(signal, "my-strategy", "BTCUSDT");
+ * ```
+ */
 const PersistSignalAdaper = new PersistSignalUtils();
 
 const INTERVAL_MINUTES$1 = {
@@ -676,6 +1110,48 @@ const INTERVAL_MINUTES$1 = {
     "30m": 30,
     "1h": 60,
 };
+const VALIDATE_SIGNAL_FN = (signal) => {
+    const errors = [];
+    // Валидация цен
+    if (signal.priceOpen <= 0) {
+        errors.push(`priceOpen must be positive, got ${signal.priceOpen}`);
+    }
+    if (signal.priceTakeProfit <= 0) {
+        errors.push(`priceTakeProfit must be positive, got ${signal.priceTakeProfit}`);
+    }
+    if (signal.priceStopLoss <= 0) {
+        errors.push(`priceStopLoss must be positive, got ${signal.priceStopLoss}`);
+    }
+    // Валидация для long позиции
+    if (signal.position === "long") {
+        if (signal.priceTakeProfit <= signal.priceOpen) {
+            errors.push(`Long: priceTakeProfit (${signal.priceTakeProfit}) must be > priceOpen (${signal.priceOpen})`);
+        }
+        if (signal.priceStopLoss >= signal.priceOpen) {
+            errors.push(`Long: priceStopLoss (${signal.priceStopLoss}) must be < priceOpen (${signal.priceOpen})`);
+        }
+    }
+    // Валидация для short позиции
+    if (signal.position === "short") {
+        if (signal.priceTakeProfit >= signal.priceOpen) {
+            errors.push(`Short: priceTakeProfit (${signal.priceTakeProfit}) must be < priceOpen (${signal.priceOpen})`);
+        }
+        if (signal.priceStopLoss <= signal.priceOpen) {
+            errors.push(`Short: priceStopLoss (${signal.priceStopLoss}) must be > priceOpen (${signal.priceOpen})`);
+        }
+    }
+    // Валидация временных параметров
+    if (signal.minuteEstimatedTime <= 0) {
+        errors.push(`minuteEstimatedTime must be positive, got ${signal.minuteEstimatedTime}`);
+    }
+    if (signal.timestamp <= 0) {
+        errors.push(`timestamp must be positive, got ${signal.timestamp}`);
+    }
+    // Кидаем ошибку если есть проблемы
+    if (errors.length > 0) {
+        throw new Error(`Invalid signal for ${signal.position} position:\n${errors.join("\n")}`);
+    }
+};
 const GET_SIGNAL_FN = trycatch(async (self) => {
     const currentTime = self.params.execution.context.when.getTime();
     {
@@ -692,10 +1168,17 @@ const GET_SIGNAL_FN = trycatch(async (self) => {
     if (!signal) {
         return null;
     }
-    return {
+    const signalRow = {
         id: randomString(),
         ...signal,
+        symbol: self.params.execution.context.symbol,
+        exchangeName: self.params.method.context.exchangeName,
+        strategyName: self.params.method.context.strategyName,
+        timestamp: currentTime,
     };
+    // Валидируем сигнал перед возвратом
+    VALIDATE_SIGNAL_FN(signalRow);
+    return signalRow;
 }, {
     defaultValue: null,
 });
@@ -714,15 +1197,70 @@ const WAIT_FOR_INIT_FN = async (self) => {
     if (self.params.execution.context.backtest) {
         return;
     }
-    self._pendingSignal = await PersistSignalAdaper.readSignalData(self.params.strategyName, self.params.execution.context.symbol);
+    const pendingSignal = await PersistSignalAdaper.readSignalData(self.params.strategyName, self.params.execution.context.symbol);
+    if (!pendingSignal) {
+        return;
+    }
+    if (pendingSignal.exchangeName !== self.params.method.context.exchangeName) {
+        return;
+    }
+    if (pendingSignal.strategyName !== self.params.method.context.strategyName) {
+        return;
+    }
+    self._pendingSignal = pendingSignal;
 };
+/**
+ * Client implementation for trading strategy lifecycle management.
+ *
+ * Features:
+ * - Signal generation with interval throttling
+ * - Automatic signal validation (prices, TP/SL logic, timestamps)
+ * - Crash-safe persistence in live mode
+ * - VWAP-based TP/SL monitoring
+ * - Fast backtest with candle array processing
+ *
+ * All methods use prototype functions for memory efficiency.
+ *
+ * @example
+ * ```typescript
+ * const strategy = new ClientStrategy({
+ *   strategyName: "my-strategy",
+ *   interval: "5m",
+ *   getSignal: async (symbol) => ({ ... }),
+ *   execution: executionService,
+ *   exchange: exchangeService,
+ *   logger: loggerService,
+ * });
+ *
+ * await strategy.waitForInit(); // Load persisted state
+ * const result = await strategy.tick(); // Monitor signal
+ * ```
+ */
 class ClientStrategy {
     constructor(params) {
         this.params = params;
         this._pendingSignal = null;
         this._lastSignalTimestamp = null;
+        /**
+         * Initializes strategy state by loading persisted signal from disk.
+         *
+         * Uses singleshot pattern to ensure initialization happens exactly once.
+         * In backtest mode: skips persistence, no state to load
+         * In live mode: reads last signal state from disk
+         *
+         * @returns Promise that resolves when initialization is complete
+         */
         this.waitForInit = singleshot(async () => await WAIT_FOR_INIT_FN(this));
     }
+    /**
+     * Updates pending signal and persists to disk in live mode.
+     *
+     * Centralized method for all signal state changes.
+     * Uses atomic file writes to prevent corruption.
+     *
+     * @param pendingSignal - New signal state (null to clear)
+     * @returns Promise that resolves when update is complete
+     */
     async setPendingSignal(pendingSignal) {
         this.params.logger.debug("ClientStrategy setPendingSignal", {
             pendingSignal,
@@ -733,6 +1271,29 @@ class ClientStrategy {
         }
         await PersistSignalAdaper.writeSignalData(this._pendingSignal, this.params.strategyName, this.params.execution.context.symbol);
     }
+    /**
+     * Performs a single tick of strategy execution.
+     *
+     * Flow:
+     * 1. If no pending signal: call getSignal with throttling and validation
+     * 2. If signal opened: trigger onOpen callback, persist state
+     * 3. If pending signal exists: check VWAP against TP/SL
+     * 4. If TP/SL/time reached: close signal, trigger onClose, persist state
+     *
+     * @returns Promise resolving to discriminated union result:
+     * - idle: No signal generated
+     * - opened: New signal just created
+     * - active: Signal monitoring in progress
+     * - closed: Signal completed with PNL
+     *
+     * @example
+     * ```typescript
+     * const result = await strategy.tick();
+     * if (result.action === "closed") {
+     *   console.log(`PNL: ${result.pnl.pnlPercentage}%`);
+     * }
+     * ```
+     */
     async tick() {
         this.params.logger.debug("ClientStrategy tick");
         if (!this._pendingSignal) {
@@ -740,17 +1301,35 @@ class ClientStrategy {
             await this.setPendingSignal(pendingSignal);
             if (this._pendingSignal) {
                 if (this.params.callbacks?.onOpen) {
-                    this.params.callbacks.onOpen(this.params.execution.context.backtest, this.params.execution.context.symbol, this._pendingSignal);
+                    this.params.callbacks.onOpen(this.params.execution.context.symbol, this._pendingSignal, this._pendingSignal.priceOpen, this.params.execution.context.backtest);
                 }
-                return {
+                const result = {
                     action: "opened",
                     signal: this._pendingSignal,
+                    strategyName: this.params.method.context.strategyName,
+                    exchangeName: this.params.method.context.exchangeName,
+                    currentPrice: this._pendingSignal.priceOpen,
                 };
+                if (this.params.callbacks?.onTick) {
+                    this.params.callbacks.onTick(this.params.execution.context.symbol, result, this.params.execution.context.backtest);
+                }
+                return result;
             }
-            return {
+            const currentPrice = await this.params.exchange.getAveragePrice(this.params.execution.context.symbol);
+            if (this.params.callbacks?.onIdle) {
+                this.params.callbacks.onIdle(this.params.execution.context.symbol, currentPrice, this.params.execution.context.backtest);
+            }
+            const result = {
                 action: "idle",
                 signal: null,
+                strategyName: this.params.method.context.strategyName,
+                exchangeName: this.params.method.context.exchangeName,
+                currentPrice,
             };
+            if (this.params.callbacks?.onTick) {
+                this.params.callbacks.onTick(this.params.execution.context.symbol, result, this.params.execution.context.backtest);
+            }
+            return result;
         }
         const when = this.params.execution.context.when;
         const signal = this._pendingSignal;
@@ -796,6 +1375,14 @@ class ClientStrategy {
         if (shouldClose) {
             const pnl = toProfitLossDto(signal, averagePrice);
             const closeTimestamp = this.params.execution.context.when.getTime();
+            // Предупреждение о закрытии сигнала в убыток
+            if (closeReason === "stop_loss") {
+                this.params.logger.warn(`ClientStrategy tick: Signal closed with loss (stop_loss), PNL: ${pnl.pnlPercentage.toFixed(2)}%`);
+            }
+            // Предупреждение о закрытии сигнала в убыток
+            if (closeReason === "time_expired" && pnl.pnlPercentage < 0) {
+                this.params.logger.warn(`ClientStrategy tick: Signal closed with loss (time_expired), PNL: ${pnl.pnlPercentage.toFixed(2)}%`);
+            }
             this.params.logger.debug("ClientStrategy closing", {
                 symbol: this.params.execution.context.symbol,
                 signalId: signal.id,
@@ -805,24 +1392,58 @@ class ClientStrategy {
                 pnlPercentage: pnl.pnlPercentage,
             });
             if (this.params.callbacks?.onClose) {
-                this.params.callbacks.onClose(this.params.execution.context.backtest, this.params.execution.context.symbol, averagePrice, signal);
+                this.params.callbacks.onClose(this.params.execution.context.symbol, signal, averagePrice, this.params.execution.context.backtest);
             }
             await this.setPendingSignal(null);
-            return {
+            const result = {
                 action: "closed",
                 signal: signal,
                 currentPrice: averagePrice,
                 closeReason: closeReason,
                 closeTimestamp: closeTimestamp,
                 pnl: pnl,
+                strategyName: this.params.method.context.strategyName,
+                exchangeName: this.params.method.context.exchangeName,
             };
+            if (this.params.callbacks?.onTick) {
+                this.params.callbacks.onTick(this.params.execution.context.symbol, result, this.params.execution.context.backtest);
+            }
+            return result;
+        }
+        if (this.params.callbacks?.onActive) {
+            this.params.callbacks.onActive(this.params.execution.context.symbol, signal, averagePrice, this.params.execution.context.backtest);
         }
-        return {
+        const result = {
             action: "active",
             signal: signal,
             currentPrice: averagePrice,
+            strategyName: this.params.method.context.strategyName,
+            exchangeName: this.params.method.context.exchangeName,
         };
+        if (this.params.callbacks?.onTick) {
+            this.params.callbacks.onTick(this.params.execution.context.symbol, result, this.params.execution.context.backtest);
+        }
+        return result;
     }
+    /**
+     * Fast backtests a pending signal using historical candle data.
+     *
+     * Iterates through candles checking VWAP against TP/SL on each timeframe.
+     * Starts from index 4 (needs 5 candles for VWAP calculation).
+     * Always returns closed result (either TP/SL or time_expired).
+     *
+     * @param candles - Array of candles covering signal's minuteEstimatedTime
+     * @returns Promise resolving to closed signal result with PNL
+     * @throws Error if no pending signal or not in backtest mode
+     *
+     * @example
+     * ```typescript
+     * // After signal opened in backtest
+     * const candles = await exchange.getNextCandles("BTCUSDT", "1m", signal.minuteEstimatedTime);
+     * const result = await strategy.backtest(candles);
+     * console.log(result.closeReason); // "take_profit" | "stop_loss" | "time_expired"
+     * ```
+     */
     async backtest(candles) {
         this.params.logger.debug("ClientStrategy backtest", {
             symbol: this.params.execution.context.symbol,
@@ -835,6 +1456,10 @@ class ClientStrategy {
         if (!this.params.execution.context.backtest) {
             throw new Error("ClientStrategy backtest: running in live context");
         }
+        // Предупреждение если недостаточно свечей для VWAP
+        if (candles.length < 5) {
+            this.params.logger.warn(`ClientStrategy backtest: Expected at least 5 candles for VWAP, got ${candles.length}`);
+        }
         // Проверяем каждую свечу на достижение TP/SL
         // Начинаем с индекса 4 (пятая свеча), чтобы было минимум 5 свечей для VWAP
         for (let i = 4; i < candles.length; i++) {
@@ -877,18 +1502,28 @@ class ClientStrategy {
                     closeTimestamp,
                     pnlPercentage: pnl.pnlPercentage,
                 });
+                // Предупреждение при убытке от stop_loss
+                if (closeReason === "stop_loss") {
+                    this.params.logger.warn(`ClientStrategy backtest: Signal closed with loss (stop_loss), PNL: ${pnl.pnlPercentage.toFixed(2)}%`);
+                }
                 if (this.params.callbacks?.onClose) {
-                    this.params.callbacks.onClose(this.params.execution.context.backtest, this.params.execution.context.symbol, averagePrice, signal);
+                    this.params.callbacks.onClose(this.params.execution.context.symbol, signal, averagePrice, this.params.execution.context.backtest);
                 }
                 await this.setPendingSignal(null);
-                return {
+                const result = {
                     action: "closed",
                     signal: signal,
                     currentPrice: averagePrice,
                     closeReason: closeReason,
                     closeTimestamp: closeTimestamp,
                     pnl: pnl,
+                    strategyName: this.params.method.context.strategyName,
+                    exchangeName: this.params.method.context.exchangeName,
                 };
+                if (this.params.callbacks?.onTick) {
+                    this.params.callbacks.onTick(this.params.execution.context.symbol, result, this.params.execution.context.backtest);
+                }
+                return result;
             }
         }
         // Если TP/SL не достигнут за период, вычисляем VWAP из последних 5 свечей
@@ -903,21 +1538,73 @@ class ClientStrategy {
             closeTimestamp,
             pnlPercentage: pnl.pnlPercentage,
         });
+        // Предупреждение при убытке от time_expired
+        if (pnl.pnlPercentage < 0) {
+            this.params.logger.warn(`ClientStrategy backtest: Signal closed with loss (time_expired), PNL: ${pnl.pnlPercentage.toFixed(2)}%`);
+        }
         if (this.params.callbacks?.onClose) {
-            this.params.callbacks.onClose(this.params.execution.context.backtest, this.params.execution.context.symbol, lastPrice, signal);
+            this.params.callbacks.onClose(this.params.execution.context.symbol, signal, lastPrice, this.params.execution.context.backtest);
         }
         await this.setPendingSignal(null);
-        return {
+        const result = {
             action: "closed",
             signal: signal,
             currentPrice: lastPrice,
             closeReason: "time_expired",
             closeTimestamp: closeTimestamp,
             pnl: pnl,
+            strategyName: this.params.method.context.strategyName,
+            exchangeName: this.params.method.context.exchangeName,
         };
+        if (this.params.callbacks?.onTick) {
+            this.params.callbacks.onTick(this.params.execution.context.symbol, result, this.params.execution.context.backtest);
+        }
+        return result;
     }
 }
 
+/**
+ * Global signal emitter for all trading events (live + backtest).
+ * Emits all signal events regardless of execution mode.
+ */
+const signalEmitter = new Subject();
+/**
+ * Live trading signal emitter.
+ * Emits only signals from live trading execution.
+ */
+const signalLiveEmitter = new Subject();
+/**
+ * Backtest signal emitter.
+ * Emits only signals from backtest execution.
+ */
+const signalBacktestEmitter = new Subject();
+/**
+ * Error emitter for background execution errors.
+ * Emits errors caught in background tasks (Live.background, Backtest.background).
+ */
+const errorEmitter = new Subject();
+
+/**
+ * Connection service routing strategy operations to correct ClientStrategy instance.
+ *
+ * Routes all IStrategy method calls to the appropriate strategy implementation
+ * based on methodContextService.context.strategyName. Uses memoization to cache
+ * ClientStrategy instances for performance.
+ *
+ * Key features:
+ * - Automatic strategy routing via method context
+ * - Memoized ClientStrategy instances by strategyName
+ * - Implements IStrategy interface
+ * - Ensures initialization with waitForInit() before operations
+ * - Handles both tick() (live) and backtest() operations
+ *
+ * @example
+ * ```typescript
+ * // Used internally by framework
+ * const result = await strategyConnectionService.tick();
+ * // Automatically routes to correct strategy based on methodContext
+ * ```
+ */
 class StrategyConnectionService {
     constructor() {
         this.loggerService = inject(TYPES.loggerService);
@@ -925,11 +1612,21 @@ class StrategyConnectionService {
         this.strategySchemaService = inject(TYPES.strategySchemaService);
         this.exchangeConnectionService = inject(TYPES.exchangeConnectionService);
         this.methodContextService = inject(TYPES.methodContextService);
-        this.getStrategy = memoize((strategyName) => `${strategyName}`, (strategyName) => {
+        /**
+         * Retrieves memoized ClientStrategy instance for given strategy name.
+         *
+         * Creates ClientStrategy on first call, returns cached instance on subsequent calls.
+         * Cache key is strategyName string.
+         *
+         * @param strategyName - Name of registered strategy schema
+         * @returns Configured ClientStrategy instance
+         */
+        this.getStrategy = memoize(([strategyName]) => `${strategyName}`, (strategyName) => {
             const { getSignal, interval, callbacks } = this.strategySchemaService.get(strategyName);
             return new ClientStrategy({
                 interval,
                 execution: this.executionContextService,
+                method: this.methodContextService,
                 logger: this.loggerService,
                 exchange: this.exchangeConnectionService,
                 strategyName,
@@ -937,21 +1634,61 @@ class StrategyConnectionService {
                 callbacks,
             });
         });
+        /**
+         * Executes live trading tick for current strategy.
+         *
+         * Waits for strategy initialization before processing tick.
+         * Evaluates current market conditions and returns signal state.
+         *
+         * @returns Promise resolving to tick result (idle, opened, active, closed)
+         */
         this.tick = async () => {
             this.loggerService.log("strategyConnectionService tick");
             const strategy = await this.getStrategy(this.methodContextService.context.strategyName);
             await strategy.waitForInit();
-            return await strategy.tick();
+            const tick = await strategy.tick();
+            {
+                if (this.executionContextService.context.backtest) {
+                    signalBacktestEmitter.next(tick);
+                }
+                if (!this.executionContextService.context.backtest) {
+                    signalLiveEmitter.next(tick);
+                }
+                signalEmitter.next(tick);
+            }
+            return tick;
         };
+        /**
+         * Executes backtest for current strategy with provided candles.
+         *
+         * Waits for strategy initialization before processing candles.
+         * Evaluates strategy signals against historical data.
+         *
+         * @param candles - Array of historical candle data to backtest
+         * @returns Promise resolving to backtest result (signal or idle)
+         */
         this.backtest = async (candles) => {
-            this.loggerService.log("strategyConnectionService backtest");
+            this.loggerService.log("strategyConnectionService backtest", {
+                candleCount: candles.length,
+            });
             const strategy = await this.getStrategy(this.methodContextService.context.strategyName);
             await strategy.waitForInit();
-            return await strategy.backtest(candles);
+            const tick = await strategy.backtest(candles);
+            {
+                if (this.executionContextService.context.backtest) {
+                    signalBacktestEmitter.next(tick);
+                }
+                signalEmitter.next(tick);
+            }
+            return tick;
         };
     }
 }
 
+/**
+ * Maps FrameInterval to minutes for timestamp calculation.
+ * Used to generate timeframe arrays with proper spacing.
+ */
 const INTERVAL_MINUTES = {
     "1m": 1,
     "3m": 3,
@@ -967,6 +1704,15 @@ const INTERVAL_MINUTES = {
     "1d": 1440,
     "3d": 4320,
 };
+/**
+ * Generates timeframe array from startDate to endDate with specified interval.
+ * Uses prototype function pattern for memory efficiency.
+ *
+ * @param symbol - Trading pair symbol (unused, for API consistency)
+ * @param self - ClientFrame instance reference
+ * @returns Array of Date objects representing tick timestamps
+ * @throws Error if interval is unknown
+ */
 const GET_TIMEFRAME_FN = async (symbol, self) => {
     self.params.logger.debug("ClientFrame getTimeframe", {
         symbol,
@@ -987,19 +1733,69 @@ const GET_TIMEFRAME_FN = async (symbol, self) => {
     }
     return timeframes;
 };
+/**
+ * Client implementation for backtest timeframe generation.
+ *
+ * Features:
+ * - Generates timestamp arrays for backtest iteration
+ * - Singleshot caching prevents redundant generation
+ * - Configurable interval spacing (1m to 3d)
+ * - Callback support for validation and logging
+ *
+ * Used by BacktestLogicPrivateService to iterate through historical periods.
+ */
 class ClientFrame {
     constructor(params) {
         this.params = params;
+        /**
+         * Generates timeframe array for backtest period.
+         * Results are cached via singleshot pattern.
+         *
+         * @param symbol - Trading pair symbol (unused, for API consistency)
+         * @returns Promise resolving to array of Date objects
+         * @throws Error if interval is invalid
+         */
         this.getTimeframe = singleshot(async (symbol) => await GET_TIMEFRAME_FN(symbol, this));
     }
 }
 
+/**
+ * Connection service routing frame operations to correct ClientFrame instance.
+ *
+ * Routes all IFrame method calls to the appropriate frame implementation
+ * based on methodContextService.context.frameName. Uses memoization to cache
+ * ClientFrame instances for performance.
+ *
+ * Key features:
+ * - Automatic frame routing via method context
+ * - Memoized ClientFrame instances by frameName
+ * - Implements IFrame interface
+ * - Backtest timeframe management (startDate, endDate, interval)
+ *
+ * Note: frameName is empty string for live mode (no frame constraints).
+ *
+ * @example
+ * ```typescript
+ * // Used internally by framework
+ * const timeframe = await frameConnectionService.getTimeframe("BTCUSDT");
+ * // Automatically routes to correct frame based on methodContext
+ * ```
+ */
 class FrameConnectionService {
     constructor() {
         this.loggerService = inject(TYPES.loggerService);
         this.frameSchemaService = inject(TYPES.frameSchemaService);
         this.methodContextService = inject(TYPES.methodContextService);
-        this.getFrame = memoize((frameName) => `${frameName}`, (frameName) => {
+        /**
+         * Retrieves memoized ClientFrame instance for given frame name.
+         *
+         * Creates ClientFrame on first call, returns cached instance on subsequent calls.
+         * Cache key is frameName string.
+         *
+         * @param frameName - Name of registered frame schema
+         * @returns Configured ClientFrame instance
+         */
+        this.getFrame = memoize(([frameName]) => `${frameName}`, (frameName) => {
             const { endDate, interval, startDate, callbacks } = this.frameSchemaService.get(frameName);
             return new ClientFrame({
                 frameName,
@@ -1010,6 +1806,15 @@ class FrameConnectionService {
                 callbacks,
             });
         });
+        /**
+         * Retrieves backtest timeframe boundaries for symbol.
+         *
+         * Returns startDate and endDate from frame configuration.
+         * Used to limit backtest execution to specific date range.
+         *
+         * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+         * @returns Promise resolving to { startDate: Date, endDate: Date }
+         */
         this.getTimeframe = async (symbol) => {
             this.loggerService.log("frameConnectionService getTimeframe", {
                 symbol,
@@ -1019,10 +1824,28 @@ class FrameConnectionService {
     }
 }
 
+/**
+ * Global service for exchange operations with execution context injection.
+ *
+ * Wraps ExchangeConnectionService with ExecutionContextService to inject
+ * symbol, when, and backtest parameters into the execution context.
+ *
+ * Used internally by BacktestLogicPrivateService and LiveLogicPrivateService.
+ */
 class ExchangeGlobalService {
     constructor() {
         this.loggerService = inject(TYPES.loggerService);
         this.exchangeConnectionService = inject(TYPES.exchangeConnectionService);
+        /**
+         * Fetches historical candles with execution context.
+         *
+         * @param symbol - Trading pair symbol
+         * @param interval - Candle interval (e.g., "1m", "1h")
+         * @param limit - Maximum number of candles to fetch
+         * @param when - Timestamp for context (used in backtest mode)
+         * @param backtest - Whether running in backtest mode
+         * @returns Promise resolving to array of candles
+         */
         this.getCandles = async (symbol, interval, limit, when, backtest) => {
             this.loggerService.log("exchangeGlobalService getCandles", {
                 symbol,
@@ -1039,6 +1862,16 @@ class ExchangeGlobalService {
                 backtest,
             });
         };
+        /**
+         * Fetches future candles (backtest mode only) with execution context.
+         *
+         * @param symbol - Trading pair symbol
+         * @param interval - Candle interval
+         * @param limit - Maximum number of candles to fetch
+         * @param when - Timestamp for context
+         * @param backtest - Whether running in backtest mode (must be true)
+         * @returns Promise resolving to array of future candles
+         */
         this.getNextCandles = async (symbol, interval, limit, when, backtest) => {
             this.loggerService.log("exchangeGlobalService getNextCandles", {
                 symbol,
@@ -1055,6 +1888,14 @@ class ExchangeGlobalService {
                 backtest,
             });
         };
+        /**
+         * Calculates VWAP with execution context.
+         *
+         * @param symbol - Trading pair symbol
+         * @param when - Timestamp for context
+         * @param backtest - Whether running in backtest mode
+         * @returns Promise resolving to VWAP price
+         */
         this.getAveragePrice = async (symbol, when, backtest) => {
             this.loggerService.log("exchangeGlobalService getAveragePrice", {
                 symbol,
@@ -1069,6 +1910,15 @@ class ExchangeGlobalService {
                 backtest,
             });
         };
+        /**
+         * Formats price with execution context.
+         *
+         * @param symbol - Trading pair symbol
+         * @param price - Price to format
+         * @param when - Timestamp for context
+         * @param backtest - Whether running in backtest mode
+         * @returns Promise resolving to formatted price string
+         */
         this.formatPrice = async (symbol, price, when, backtest) => {
             this.loggerService.log("exchangeGlobalService formatPrice", {
                 symbol,
@@ -1084,6 +1934,15 @@ class ExchangeGlobalService {
                 backtest,
             });
         };
+        /**
+         * Formats quantity with execution context.
+         *
+         * @param symbol - Trading pair symbol
+         * @param quantity - Quantity to format
+         * @param when - Timestamp for context
+         * @param backtest - Whether running in backtest mode
+         * @returns Promise resolving to formatted quantity string
+         */
         this.formatQuantity = async (symbol, quantity, when, backtest) => {
             this.loggerService.log("exchangeGlobalService formatQuantity", {
                 symbol,
@@ -1102,10 +1961,29 @@ class ExchangeGlobalService {
     }
 }
 
+/**
+ * Global service for strategy operations with execution context injection.
+ *
+ * Wraps StrategyConnectionService with ExecutionContextService to inject
+ * symbol, when, and backtest parameters into the execution context.
+ *
+ * Used internally by BacktestLogicPrivateService and LiveLogicPrivateService.
+ */
 class StrategyGlobalService {
     constructor() {
         this.loggerService = inject(TYPES.loggerService);
         this.strategyConnectionService = inject(TYPES.strategyConnectionService);
+        /**
+         * Checks signal status at a specific timestamp.
+         *
+         * Wraps strategy tick() with execution context containing symbol, timestamp,
+         * and backtest mode flag.
+         *
+         * @param symbol - Trading pair symbol
+         * @param when - Timestamp for tick evaluation
+         * @param backtest - Whether running in backtest mode
+         * @returns Discriminated union of tick result (idle, opened, active, closed)
+         */
         this.tick = async (symbol, when, backtest) => {
             this.loggerService.log("strategyGlobalService tick", {
                 symbol,
@@ -1120,9 +1998,22 @@ class StrategyGlobalService {
                 backtest,
             });
         };
+        /**
+         * Runs fast backtest against candle array.
+         *
+         * Wraps strategy backtest() with execution context containing symbol,
+         * timestamp, and backtest mode flag.
+         *
+         * @param symbol - Trading pair symbol
+         * @param candles - Array of historical candles to test against
+         * @param when - Starting timestamp for backtest
+         * @param backtest - Whether running in backtest mode (typically true)
+         * @returns Closed signal result with PNL
+         */
         this.backtest = async (symbol, candles, when, backtest) => {
             this.loggerService.log("strategyGlobalService backtest", {
                 symbol,
+                candleCount: candles.length,
                 when,
                 backtest,
             });
@@ -1137,10 +2028,22 @@ class StrategyGlobalService {
     }
 }
 
+/**
+ * Global service for frame operations.
+ *
+ * Wraps FrameConnectionService for timeframe generation.
+ * Used internally by BacktestLogicPrivateService.
+ */
 class FrameGlobalService {
     constructor() {
         this.loggerService = inject(TYPES.loggerService);
         this.frameConnectionService = inject(TYPES.frameConnectionService);
+        /**
+         * Generates timeframe array for backtest iteration.
+         *
+         * @param symbol - Trading pair symbol
+         * @returns Promise resolving to array of Date objects
+         */
         this.getTimeframe = async (symbol) => {
             this.loggerService.log("frameGlobalService getTimeframe", {
                 symbol,
@@ -1150,61 +2053,247 @@ class FrameGlobalService {
     }
 }
 
+/**
+ * Service for managing exchange schema registry.
+ *
+ * Uses ToolRegistry from functools-kit for type-safe schema storage.
+ * Exchanges are registered via addExchange() and retrieved by name.
+ */
 class ExchangeSchemaService {
     constructor() {
         this.loggerService = inject(TYPES.loggerService);
         this._registry = new ToolRegistry("exchangeSchema");
+        /**
+         * Registers a new exchange schema.
+         *
+         * @param key - Unique exchange name
+         * @param value - Exchange schema configuration
+         * @throws Error if exchange name already exists
+         */
         this.register = (key, value) => {
-            this.loggerService.info(`exchangeSchemaService register`, { key });
+            this.loggerService.log(`exchangeSchemaService register`, { key });
+            this.validateShallow(value);
             this._registry = this._registry.register(key, value);
         };
+        /**
+         * Validates exchange schema structure for required properties.
+         *
+         * Performs shallow validation to ensure all required properties exist
+         * and have correct types before registration in the registry.
+         *
+         * @param exchangeSchema - Exchange schema to validate
+         * @throws Error if exchangeName is missing or not a string
+         * @throws Error if getCandles is missing or not a function
+         * @throws Error if formatPrice is missing or not a function
+         * @throws Error if formatQuantity is missing or not a function
+         */
+        this.validateShallow = (exchangeSchema) => {
+            this.loggerService.log(`exchangeSchemaService validateShallow`, {
+                exchangeSchema,
+            });
+            if (typeof exchangeSchema.exchangeName !== "string") {
+                throw new Error(`exchange schema validation failed: missing exchangeName`);
+            }
+            if (typeof exchangeSchema.getCandles !== "function") {
+                throw new Error(`exchange schema validation failed: missing getCandles for exchangeName=${exchangeSchema.exchangeName}`);
+            }
+            if (typeof exchangeSchema.formatPrice !== "function") {
+                throw new Error(`exchange schema validation failed: missing formatPrice for exchangeName=${exchangeSchema.exchangeName}`);
+            }
+            if (typeof exchangeSchema.formatQuantity !== "function") {
+                throw new Error(`exchange schema validation failed: missing formatQuantity for exchangeName=${exchangeSchema.exchangeName}`);
+            }
+        };
+        /**
+         * Overrides an existing exchange schema with partial updates.
+         *
+         * @param key - Exchange name to override
+         * @param value - Partial schema updates
+         * @returns Updated exchange schema
+         * @throws Error if exchange name doesn't exist
+         */
         this.override = (key, value) => {
-            this.loggerService.info(`exchangeSchemaService override`, { key });
+            this.loggerService.log(`exchangeSchemaService override`, { key });
             this._registry = this._registry.override(key, value);
             return this._registry.get(key);
         };
+        /**
+         * Retrieves an exchange schema by name.
+         *
+         * @param key - Exchange name
+         * @returns Exchange schema configuration
+         * @throws Error if exchange name doesn't exist
+         */
         this.get = (key) => {
-            this.loggerService.info(`exchangeSchemaService get`, { key });
+            this.loggerService.log(`exchangeSchemaService get`, { key });
             return this._registry.get(key);
         };
     }
 }
 
+/**
+ * Service for managing strategy schema registry.
+ *
+ * Uses ToolRegistry from functools-kit for type-safe schema storage.
+ * Strategies are registered via addStrategy() and retrieved by name.
+ */
 class StrategySchemaService {
     constructor() {
         this.loggerService = inject(TYPES.loggerService);
         this._registry = new ToolRegistry("strategySchema");
+        /**
+         * Registers a new strategy schema.
+         *
+         * @param key - Unique strategy name
+         * @param value - Strategy schema configuration
+         * @throws Error if strategy name already exists
+         */
         this.register = (key, value) => {
-            this.loggerService.info(`strategySchemaService register`, { key });
+            this.loggerService.log(`strategySchemaService register`, { key });
+            this.validateShallow(value);
             this._registry = this._registry.register(key, value);
         };
+        /**
+         * Validates strategy schema structure for required properties.
+         *
+         * Performs shallow validation to ensure all required properties exist
+         * and have correct types before registration in the registry.
+         *
+         * @param strategySchema - Strategy schema to validate
+         * @throws Error if strategyName is missing or not a string
+         * @throws Error if interval is missing or not a valid SignalInterval
+         * @throws Error if getSignal is missing or not a function
+         */
+        this.validateShallow = (strategySchema) => {
+            this.loggerService.log(`strategySchemaService validateShallow`, {
+                strategySchema,
+            });
+            if (typeof strategySchema.strategyName !== "string") {
+                throw new Error(`strategy schema validation failed: missing strategyName`);
+            }
+            if (typeof strategySchema.interval !== "string") {
+                throw new Error(`strategy schema validation failed: missing interval for strategyName=${strategySchema.strategyName}`);
+            }
+            if (typeof strategySchema.getSignal !== "function") {
+                throw new Error(`strategy schema validation failed: missing getSignal for strategyName=${strategySchema.strategyName}`);
+            }
+        };
+        /**
+         * Overrides an existing strategy schema with partial updates.
+         *
+         * @param key - Strategy name to override
+         * @param value - Partial schema updates
+         * @returns Updated strategy schema
+         * @throws Error if strategy name doesn't exist
+         */
         this.override = (key, value) => {
-            this.loggerService.info(`strategySchemaService override`, { key });
+            this.loggerService.log(`strategySchemaService override`, { key });
             this._registry = this._registry.override(key, value);
             return this._registry.get(key);
         };
+        /**
+         * Retrieves a strategy schema by name.
+         *
+         * @param key - Strategy name
+         * @returns Strategy schema configuration
+         * @throws Error if strategy name doesn't exist
+         */
         this.get = (key) => {
-            this.loggerService.info(`strategySchemaService get`, { key });
+            this.loggerService.log(`strategySchemaService get`, { key });
             return this._registry.get(key);
         };
     }
 }
 
+/**
+ * Service for managing frame schema registry.
+ *
+ * Uses ToolRegistry from functools-kit for type-safe schema storage.
+ * Frames are registered via addFrame() and retrieved by name.
+ */
 class FrameSchemaService {
     constructor() {
+        this.loggerService = inject(TYPES.loggerService);
         this._registry = new ToolRegistry("frameSchema");
+        /**
+         * Validates frame schema structure for required properties.
+         *
+         * Performs shallow validation to ensure all required properties exist
+         * and have correct types before registration in the registry.
+         *
+         * @param frameSchema - Frame schema to validate
+         * @throws Error if frameName is missing or not a string
+         * @throws Error if interval is missing or not a valid FrameInterval
+         * @throws Error if startDate is missing or not a Date
+         * @throws Error if endDate is missing or not a Date
+         */
+        this.validateShallow = (frameSchema) => {
+            this.loggerService.log(`frameSchemaService validateShallow`, {
+                frameSchema,
+            });
+            if (typeof frameSchema.frameName !== "string") {
+                throw new Error(`frame schema validation failed: missing frameName`);
+            }
+            if (typeof frameSchema.interval !== "string") {
+                throw new Error(`frame schema validation failed: missing interval for frameName=${frameSchema.frameName}`);
+            }
+            if (!(frameSchema.startDate instanceof Date)) {
+                throw new Error(`frame schema validation failed: missing startDate for frameName=${frameSchema.frameName}`);
+            }
+            if (!(frameSchema.endDate instanceof Date)) {
+                throw new Error(`frame schema validation failed: missing endDate for frameName=${frameSchema.frameName}`);
+            }
+        };
     }
+    /**
+     * Registers a new frame schema.
+     *
+     * @param key - Unique frame name
+     * @param value - Frame schema configuration
+     * @throws Error if frame name already exists
+     */
     register(key, value) {
+        this.loggerService.log(`frameSchemaService register`, { key });
+        this.validateShallow(value);
         this._registry.register(key, value);
     }
+    /**
+     * Overrides an existing frame schema with partial updates.
+     *
+     * @param key - Frame name to override
+     * @param value - Partial schema updates
+     * @throws Error if frame name doesn't exist
+     */
     override(key, value) {
+        this.loggerService.log(`frameSchemaService override`, { key });
         this._registry.override(key, value);
     }
+    /**
+     * Retrieves a frame schema by name.
+     *
+     * @param key - Frame name
+     * @returns Frame schema configuration
+     * @throws Error if frame name doesn't exist
+     */
     get(key) {
+        this.loggerService.log(`frameSchemaService get`, { key });
         return this._registry.get(key);
     }
 }
 
+/**
+ * Private service for backtest orchestration using async generators.
+ *
+ * Flow:
+ * 1. Get timeframes from frame service
+ * 2. Iterate through timeframes calling tick()
+ * 3. When signal opens: fetch candles and call backtest()
+ * 4. Skip timeframes until signal closes
+ * 5. Yield closed result and continue
+ *
+ * Memory efficient: streams results without array accumulation.
+ * Supports early termination via break in consumer.
+ */
 class BacktestLogicPrivateService {
     constructor() {
         this.loggerService = inject(TYPES.loggerService);
@@ -1212,6 +2301,20 @@ class BacktestLogicPrivateService {
         this.exchangeGlobalService = inject(TYPES.exchangeGlobalService);
         this.frameGlobalService = inject(TYPES.frameGlobalService);
     }
+    /**
+     * Runs backtest for a symbol, streaming closed signals as async generator.
+     *
+     * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+     * @yields Closed signal results with PNL
+     *
+     * @example
+     * ```typescript
+     * for await (const result of backtestLogic.run("BTCUSDT")) {
+     *   console.log(result.closeReason, result.pnl.pnlPercentage);
+     *   if (result.pnl.pnlPercentage < -10) break; // Early termination
+     * }
+     * ```
+     */
     async *run(symbol) {
         this.loggerService.log("backtestLogicPrivateService run", {
             symbol,
@@ -1260,11 +2363,49 @@ class BacktestLogicPrivateService {
 }
 
 const TICK_TTL = 1 * 60 * 1000 + 1;
+/**
+ * Private service for live trading orchestration using async generators.
+ *
+ * Flow:
+ * 1. Infinite while(true) loop for continuous monitoring
+ * 2. Create real-time date with new Date()
+ * 3. Call tick() to check signal status
+ * 4. Yield opened/closed results (skip idle/active)
+ * 5. Sleep for TICK_TTL between iterations
+ *
+ * Features:
+ * - Crash recovery via ClientStrategy.waitForInit()
+ * - Real-time progression with new Date()
+ * - Memory efficient streaming
+ * - Never completes (infinite generator)
+ */
 class LiveLogicPrivateService {
     constructor() {
         this.loggerService = inject(TYPES.loggerService);
         this.strategyGlobalService = inject(TYPES.strategyGlobalService);
     }
+    /**
+     * Runs live trading for a symbol, streaming results as async generator.
+     *
+     * Infinite generator that yields opened and closed signals.
+     * Process can crash and restart - state will be recovered from disk.
+     *
+     * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+     * @yields Opened and closed signal results
+     *
+     * @example
+     * ```typescript
+     * for await (const result of liveLogic.run("BTCUSDT")) {
+     *   if (result.action === "opened") {
+     *     console.log("New signal:", result.signal.id);
+     *   }
+     *   if (result.action === "closed") {
+     *     console.log("PNL:", result.pnl.pnlPercentage);
+     *   }
+     *   // Infinite loop - will never complete
+     * }
+     * ```
+     */
     async *run(symbol) {
         this.loggerService.log("liveLogicPrivateService run", {
             symbol,
@@ -1290,10 +2431,44 @@ class LiveLogicPrivateService {
     }
 }
 
+/**
+ * Public service for backtest orchestration with context management.
+ *
+ * Wraps BacktestLogicPrivateService with MethodContextService to provide
+ * implicit context propagation for strategyName, exchangeName, and frameName.
+ *
+ * This allows getCandles(), getSignal(), and other functions to work without
+ * explicit context parameters.
+ *
+ * @example
+ * ```typescript
+ * const backtestLogicPublicService = inject(TYPES.backtestLogicPublicService);
+ *
+ * for await (const result of backtestLogicPublicService.run("BTCUSDT", {
+ *   strategyName: "my-strategy",
+ *   exchangeName: "my-exchange",
+ *   frameName: "1d-backtest",
+ * })) {
+ *   if (result.action === "closed") {
+ *     console.log("PNL:", result.pnl.profit);
+ *   }
+ * }
+ * ```
+ */
 class BacktestLogicPublicService {
     constructor() {
         this.loggerService = inject(TYPES.loggerService);
         this.backtestLogicPrivateService = inject(TYPES.backtestLogicPrivateService);
+        /**
+         * Runs backtest for a symbol with context propagation.
+         *
+         * Streams closed signals as async generator. Context is automatically
+         * injected into all framework functions called during iteration.
+         *
+         * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+         * @param context - Execution context with strategy, exchange, and frame names
+         * @returns Async generator yielding closed signals with PNL
+         */
         this.run = (symbol, context) => {
             this.loggerService.log("backtestLogicPublicService run", {
                 symbol,
@@ -1308,10 +2483,52 @@ class BacktestLogicPublicService {
     }
 }
 
+/**
+ * Public service for live trading orchestration with context management.
+ *
+ * Wraps LiveLogicPrivateService with MethodContextService to provide
+ * implicit context propagation for strategyName and exchangeName.
+ *
+ * This allows getCandles(), getSignal(), and other functions to work without
+ * explicit context parameters.
+ *
+ * Features:
+ * - Infinite async generator (never completes)
+ * - Crash recovery via persisted state
+ * - Real-time progression with Date.now()
+ *
+ * @example
+ * ```typescript
+ * const liveLogicPublicService = inject(TYPES.liveLogicPublicService);
+ *
+ * // Infinite loop - use Ctrl+C to stop
+ * for await (const result of liveLogicPublicService.run("BTCUSDT", {
+ *   strategyName: "my-strategy",
+ *   exchangeName: "my-exchange",
+ * })) {
+ *   if (result.action === "opened") {
+ *     console.log("Signal opened:", result.signal);
+ *   } else if (result.action === "closed") {
+ *     console.log("PNL:", result.pnl.profit);
+ *   }
+ * }
+ * ```
+ */
 class LiveLogicPublicService {
     constructor() {
         this.loggerService = inject(TYPES.loggerService);
         this.liveLogicPrivateService = inject(TYPES.liveLogicPrivateService);
+        /**
+         * Runs live trading for a symbol with context propagation.
+         *
+         * Streams opened and closed signals as infinite async generator.
+         * Context is automatically injected into all framework functions.
+         * Process can crash and restart - state will be recovered from disk.
+         *
+         * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+         * @param context - Execution context with strategy and exchange names
+         * @returns Infinite async generator yielding opened and closed signals
+         */
         this.run = (symbol, context) => {
             this.loggerService.log("liveLogicPublicService run", {
                 symbol,
@@ -1326,78 +2543,989 @@ class LiveLogicPublicService {
     }
 }
 
+const METHOD_NAME_RUN$1 = "liveGlobalService run";
+/**
+ * Global service providing access to live trading functionality.
+ *
+ * Simple wrapper around LiveLogicPublicService for dependency injection.
+ * Used by public API exports.
+ */
 class LiveGlobalService {
     constructor() {
         this.loggerService = inject(TYPES.loggerService);
         this.liveLogicPublicService = inject(TYPES.liveLogicPublicService);
+        this.strategyValidationService = inject(TYPES.strategyValidationService);
+        this.exchangeValidationService = inject(TYPES.exchangeValidationService);
+        /**
+         * Runs live trading for a symbol with context propagation.
+         *
+         * Infinite async generator with crash recovery support.
+         *
+         * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+         * @param context - Execution context with strategy and exchange names
+         * @returns Infinite async generator yielding opened and closed signals
+         */
         this.run = (symbol, context) => {
-            this.loggerService.log("liveGlobalService run", {
+            this.loggerService.log(METHOD_NAME_RUN$1, {
                 symbol,
                 context,
             });
+            this.strategyValidationService.validate(context.strategyName, METHOD_NAME_RUN$1);
+            this.exchangeValidationService.validate(context.exchangeName, METHOD_NAME_RUN$1);
             return this.liveLogicPublicService.run(symbol, context);
         };
     }
 }
 
+const METHOD_NAME_RUN = "backtestGlobalService run";
+/**
+ * Global service providing access to backtest functionality.
+ *
+ * Simple wrapper around BacktestLogicPublicService for dependency injection.
+ * Used by public API exports.
+ */
 class BacktestGlobalService {
     constructor() {
         this.loggerService = inject(TYPES.loggerService);
         this.backtestLogicPublicService = inject(TYPES.backtestLogicPublicService);
+        this.strategyValidationService = inject(TYPES.strategyValidationService);
+        this.exchangeValidationService = inject(TYPES.exchangeValidationService);
+        this.frameValidationService = inject(TYPES.frameValidationService);
+        /**
+         * Runs backtest for a symbol with context propagation.
+         *
+         * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+         * @param context - Execution context with strategy, exchange, and frame names
+         * @returns Async generator yielding closed signals with PNL
+         */
         this.run = (symbol, context) => {
-            this.loggerService.log("backtestGlobalService run", {
+            this.loggerService.log(METHOD_NAME_RUN, {
                 symbol,
                 context,
             });
+            this.strategyValidationService.validate(context.strategyName, METHOD_NAME_RUN);
+            this.exchangeValidationService.validate(context.exchangeName, METHOD_NAME_RUN);
+            this.frameValidationService.validate(context.frameName, METHOD_NAME_RUN);
             return this.backtestLogicPublicService.run(symbol, context);
         };
     }
 }
 
-{
-    provide(TYPES.loggerService, () => new LoggerService());
-}
-{
-    provide(TYPES.executionContextService, () => new ExecutionContextService());
-    provide(TYPES.methodContextService, () => new MethodContextService());
-}
-{
-    provide(TYPES.exchangeConnectionService, () => new ExchangeConnectionService());
-    provide(TYPES.strategyConnectionService, () => new StrategyConnectionService());
-    provide(TYPES.frameConnectionService, () => new FrameConnectionService());
-}
-{
-    provide(TYPES.exchangeSchemaService, () => new ExchangeSchemaService());
-    provide(TYPES.strategySchemaService, () => new StrategySchemaService());
-    provide(TYPES.frameSchemaService, () => new FrameSchemaService());
-}
-{
-    provide(TYPES.exchangeGlobalService, () => new ExchangeGlobalService());
-    provide(TYPES.strategyGlobalService, () => new StrategyGlobalService());
-    provide(TYPES.frameGlobalService, () => new FrameGlobalService());
-    provide(TYPES.liveGlobalService, () => new LiveGlobalService());
-    provide(TYPES.backtestGlobalService, () => new BacktestGlobalService());
-}
-{
-    provide(TYPES.backtestLogicPrivateService, () => new BacktestLogicPrivateService());
-    provide(TYPES.liveLogicPrivateService, () => new LiveLogicPrivateService());
-}
-{
-    provide(TYPES.backtestLogicPublicService, () => new BacktestLogicPublicService());
-    provide(TYPES.liveLogicPublicService, () => new LiveLogicPublicService());
-}
-
-const baseServices = {
-    loggerService: inject(TYPES.loggerService),
-};
-const contextServices = {
-    executionContextService: inject(TYPES.executionContextService),
-    methodContextService: inject(TYPES.methodContextService),
-};
-const connectionServices = {
-    exchangeConnectionService: inject(TYPES.exchangeConnectionService),
-    strategyConnectionService: inject(TYPES.strategyConnectionService),
-    frameConnectionService: inject(TYPES.frameConnectionService),
+const columns$1 = [
+    {
+        key: "signalId",
+        label: "Signal ID",
+        format: (data) => data.signal.id,
+    },
+    {
+        key: "symbol",
+        label: "Symbol",
+        format: (data) => data.signal.symbol,
+    },
+    {
+        key: "position",
+        label: "Position",
+        format: (data) => data.signal.position.toUpperCase(),
+    },
+    {
+        key: "note",
+        label: "Note",
+        format: (data) => data.signal.note ?? "N/A",
+    },
+    {
+        key: "openPrice",
+        label: "Open Price",
+        format: (data) => `${data.signal.priceOpen.toFixed(8)} USD`,
+    },
+    {
+        key: "closePrice",
+        label: "Close Price",
+        format: (data) => `${data.currentPrice.toFixed(8)} USD`,
+    },
+    {
+        key: "takeProfit",
+        label: "Take Profit",
+        format: (data) => `${data.signal.priceTakeProfit.toFixed(8)} USD`,
+    },
+    {
+        key: "stopLoss",
+        label: "Stop Loss",
+        format: (data) => `${data.signal.priceStopLoss.toFixed(8)} USD`,
+    },
+    {
+        key: "pnl",
+        label: "PNL (net)",
+        format: (data) => {
+            const pnlPercentage = data.pnl.pnlPercentage;
+            return `${pnlPercentage > 0 ? "+" : ""}${pnlPercentage.toFixed(2)}%`;
+        },
+    },
+    {
+        key: "closeReason",
+        label: "Close Reason",
+        format: (data) => data.closeReason,
+    },
+    {
+        key: "duration",
+        label: "Duration (min)",
+        format: (data) => {
+            const durationMs = data.closeTimestamp - data.signal.timestamp;
+            const durationMin = Math.round(durationMs / 60000);
+            return `${durationMin}`;
+        },
+    },
+    {
+        key: "openTimestamp",
+        label: "Open Time",
+        format: (data) => new Date(data.signal.timestamp).toISOString(),
+    },
+    {
+        key: "closeTimestamp",
+        label: "Close Time",
+        format: (data) => new Date(data.closeTimestamp).toISOString(),
+    },
+];
+/**
+ * Storage class for accumulating closed signals per strategy.
+ * Maintains a list of all closed signals and provides methods to generate reports.
+ */
+let ReportStorage$1 = class ReportStorage {
+    constructor() {
+        /** Internal list of all closed signals for this strategy */
+        this._signalList = [];
+    }
+    /**
+     * Adds a closed signal to the storage.
+     *
+     * @param data - Closed signal data with PNL and close reason
+     */
+    addSignal(data) {
+        this._signalList.push(data);
+    }
+    /**
+     * Generates markdown report with all closed signals for a strategy.
+     *
+     * @param strategyName - Strategy name
+     * @returns Markdown formatted report with all signals
+     */
+    getReport(strategyName) {
+        if (this._signalList.length === 0) {
+            return str.newline(`# Backtest Report: ${strategyName}`, "", "No signals closed yet.");
+        }
+        const header = columns$1.map((col) => col.label);
+        const rows = this._signalList.map((closedSignal) => columns$1.map((col) => col.format(closedSignal)));
+        const tableData = [header, ...rows];
+        const table = str.table(tableData);
+        return str.newline(`# Backtest Report: ${strategyName}`, "", `Total signals: ${this._signalList.length}`, "", table, "", "", `*Generated: ${new Date().toISOString()}*`);
+    }
+    /**
+     * Saves strategy report to disk.
+     *
+     * @param strategyName - Strategy name
+     * @param path - Directory path to save report (default: "./logs/backtest")
+     */
+    async dump(strategyName, path = "./logs/backtest") {
+        const markdown = this.getReport(strategyName);
+        try {
+            const dir = join(process.cwd(), path);
+            await mkdir(dir, { recursive: true });
+            const filename = `${strategyName}.md`;
+            const filepath = join(dir, filename);
+            await writeFile(filepath, markdown, "utf-8");
+            console.log(`Backtest report saved: ${filepath}`);
+        }
+        catch (error) {
+            console.error(`Failed to save markdown report:`, error);
+        }
+    }
+};
+/**
+ * Service for generating and saving backtest markdown reports.
+ *
+ * Features:
+ * - Listens to signal events via onTick callback
+ * - Accumulates closed signals per strategy using memoized storage
+ * - Generates markdown tables with detailed signal information
+ * - Saves reports to disk in logs/backtest/{strategyName}.md
+ *
+ * @example
+ * ```typescript
+ * const service = new BacktestMarkdownService();
+ *
+ * // Add to strategy callbacks
+ * addStrategy({
+ *   strategyName: "my-strategy",
+ *   callbacks: {
+ *     onTick: (symbol, result, backtest) => {
+ *       service.tick(result);
+ *     }
+ *   }
+ * });
+ *
+ * // After backtest, generate and save report
+ * await service.saveReport("my-strategy");
+ * ```
+ */
+class BacktestMarkdownService {
+    constructor() {
+        /** Logger service for debug output */
+        this.loggerService = inject(TYPES.loggerService);
+        /**
+         * Memoized function to get or create ReportStorage for a strategy.
+         * Each strategy gets its own isolated storage instance.
+         */
+        this.getStorage = memoize(([strategyName]) => `${strategyName}`, () => new ReportStorage$1());
+        /**
+         * Processes tick events and accumulates closed signals.
+         * Should be called from IStrategyCallbacks.onTick.
+         *
+         * Only processes closed signals - opened signals are ignored.
+         *
+         * @param data - Tick result from strategy execution (opened or closed)
+         *
+         * @example
+         * ```typescript
+         * const service = new BacktestMarkdownService();
+         *
+         * callbacks: {
+         *   onTick: (symbol, result, backtest) => {
+         *     service.tick(result);
+         *   }
+         * }
+         * ```
+         */
+        this.tick = async (data) => {
+            this.loggerService.log("backtestMarkdownService tick", {
+                data,
+            });
+            if (data.action !== "closed") {
+                return;
+            }
+            const storage = this.getStorage(data.strategyName);
+            storage.addSignal(data);
+        };
+        /**
+         * Generates markdown report with all closed signals for a strategy.
+         * Delegates to ReportStorage.generateReport().
+         *
+         * @param strategyName - Strategy name to generate report for
+         * @returns Markdown formatted report string with table of all closed signals
+         *
+         * @example
+         * ```typescript
+         * const service = new BacktestMarkdownService();
+         * const markdown = service.generateReport("my-strategy");
+         * console.log(markdown);
+         * ```
+         */
+        this.getReport = async (strategyName) => {
+            this.loggerService.log("backtestMarkdownService getReport", {
+                strategyName,
+            });
+            const storage = this.getStorage(strategyName);
+            return storage.getReport(strategyName);
+        };
+        /**
+         * Saves strategy report to disk.
+         * Creates directory if it doesn't exist.
+         * Delegates to ReportStorage.dump().
+         *
+         * @param strategyName - Strategy name to save report for
+         * @param path - Directory path to save report (default: "./logs/backtest")
+         *
+         * @example
+         * ```typescript
+         * const service = new BacktestMarkdownService();
+         *
+         * // Save to default path: ./logs/backtest/my-strategy.md
+         * await service.dump("my-strategy");
+         *
+         * // Save to custom path: ./custom/path/my-strategy.md
+         * await service.dump("my-strategy", "./custom/path");
+         * ```
+         */
+        this.dump = async (strategyName, path = "./logs/backtest") => {
+            this.loggerService.log("backtestMarkdownService dump", {
+                strategyName,
+                path,
+            });
+            const storage = this.getStorage(strategyName);
+            await storage.dump(strategyName, path);
+        };
+        /**
+         * Clears accumulated signal data from storage.
+         * If strategyName is provided, clears only that strategy's data.
+         * If strategyName is omitted, clears all strategies' data.
+         *
+         * @param strategyName - Optional strategy name to clear specific strategy data
+         *
+         * @example
+         * ```typescript
+         * const service = new BacktestMarkdownService();
+         *
+         * // Clear specific strategy data
+         * await service.clear("my-strategy");
+         *
+         * // Clear all strategies' data
+         * await service.clear();
+         * ```
+         */
+        this.clear = async (strategyName) => {
+            this.loggerService.log("backtestMarkdownService clear", {
+                strategyName,
+            });
+            this.getStorage.clear(strategyName);
+        };
+        /**
+         * Initializes the service by subscribing to backtest signal events.
+         * Uses singleshot to ensure initialization happens only once.
+         * Automatically called on first use.
+         *
+         * @example
+         * ```typescript
+         * const service = new BacktestMarkdownService();
+         * await service.init(); // Subscribe to backtest events
+         * ```
+         */
+        this.init = singleshot(async () => {
+            this.loggerService.log("backtestMarkdownService init");
+            signalBacktestEmitter.subscribe(this.tick);
+        });
+    }
+}
+
+const columns = [
+    {
+        key: "timestamp",
+        label: "Timestamp",
+        format: (data) => new Date(data.timestamp).toISOString(),
+    },
+    {
+        key: "action",
+        label: "Action",
+        format: (data) => data.action.toUpperCase(),
+    },
+    {
+        key: "symbol",
+        label: "Symbol",
+        format: (data) => data.symbol ?? "N/A",
+    },
+    {
+        key: "signalId",
+        label: "Signal ID",
+        format: (data) => data.signalId ?? "N/A",
+    },
+    {
+        key: "position",
+        label: "Position",
+        format: (data) => data.position?.toUpperCase() ?? "N/A",
+    },
+    {
+        key: "note",
+        label: "Note",
+        format: (data) => data.note ?? "N/A",
+    },
+    {
+        key: "currentPrice",
+        label: "Current Price",
+        format: (data) => `${data.currentPrice.toFixed(8)} USD`,
+    },
+    {
+        key: "openPrice",
+        label: "Open Price",
+        format: (data) => data.openPrice !== undefined ? `${data.openPrice.toFixed(8)} USD` : "N/A",
+    },
+    {
+        key: "takeProfit",
+        label: "Take Profit",
+        format: (data) => data.takeProfit !== undefined
+            ? `${data.takeProfit.toFixed(8)} USD`
+            : "N/A",
+    },
+    {
+        key: "stopLoss",
+        label: "Stop Loss",
+        format: (data) => data.stopLoss !== undefined ? `${data.stopLoss.toFixed(8)} USD` : "N/A",
+    },
+    {
+        key: "pnl",
+        label: "PNL (net)",
+        format: (data) => {
+            if (data.pnl === undefined)
+                return "N/A";
+            return `${data.pnl > 0 ? "+" : ""}${data.pnl.toFixed(2)}%`;
+        },
+    },
+    {
+        key: "closeReason",
+        label: "Close Reason",
+        format: (data) => data.closeReason ?? "N/A",
+    },
+    {
+        key: "duration",
+        label: "Duration (min)",
+        format: (data) => data.duration !== undefined ? `${data.duration}` : "N/A",
+    },
+];
+/** Maximum number of events to store in live trading reports */
+const MAX_EVENTS = 250;
+/**
+ * Storage class for accumulating all tick events per strategy.
+ * Maintains a chronological list of all events (idle, opened, active, closed).
+ */
+class ReportStorage {
+    constructor() {
+        /** Internal list of all tick events for this strategy */
+        this._eventList = [];
+    }
+    /**
+     * Adds an idle event to the storage.
+     * Replaces the last idle event only if there are no opened/active events after it.
+     *
+     * @param currentPrice - Current market price
+     */
+    addIdleEvent(currentPrice) {
+        const newEvent = {
+            timestamp: Date.now(),
+            action: "idle",
+            currentPrice,
+        };
+        const lastIdleIndex = this._eventList.findLastIndex((event) => event.action === "idle");
+        const canReplaceLastIdle = lastIdleIndex !== -1 &&
+            !this._eventList
+                .slice(lastIdleIndex + 1)
+                .some((event) => event.action === "opened" || event.action === "active");
+        if (canReplaceLastIdle) {
+            this._eventList[lastIdleIndex] = newEvent;
+            return;
+        }
+        {
+            this._eventList.push(newEvent);
+            if (this._eventList.length > MAX_EVENTS) {
+                this._eventList.shift();
+            }
+        }
+    }
+    /**
+     * Adds an opened event to the storage.
+     *
+     * @param data - Opened tick result
+     */
+    addOpenedEvent(data) {
+        this._eventList.push({
+            timestamp: data.signal.timestamp,
+            action: "opened",
+            symbol: data.signal.symbol,
+            signalId: data.signal.id,
+            position: data.signal.position,
+            note: data.signal.note,
+            currentPrice: data.signal.priceOpen,
+            openPrice: data.signal.priceOpen,
+            takeProfit: data.signal.priceTakeProfit,
+            stopLoss: data.signal.priceStopLoss,
+        });
+        // Trim queue if exceeded MAX_EVENTS
+        if (this._eventList.length > MAX_EVENTS) {
+            this._eventList.shift();
+        }
+    }
+    /**
+     * Updates or adds an active event to the storage.
+     * Replaces the previous event with the same signalId.
+     *
+     * @param data - Active tick result
+     */
+    addActiveEvent(data) {
+        // Find existing event with the same signalId
+        const existingIndex = this._eventList.findIndex((event) => event.signalId === data.signal.id);
+        const newEvent = {
+            timestamp: Date.now(),
+            action: "active",
+            symbol: data.signal.symbol,
+            signalId: data.signal.id,
+            position: data.signal.position,
+            note: data.signal.note,
+            currentPrice: data.currentPrice,
+            openPrice: data.signal.priceOpen,
+            takeProfit: data.signal.priceTakeProfit,
+            stopLoss: data.signal.priceStopLoss,
+        };
+        // Replace existing event or add new one
+        if (existingIndex !== -1) {
+            this._eventList[existingIndex] = newEvent;
+        }
+        else {
+            this._eventList.push(newEvent);
+            // Trim queue if exceeded MAX_EVENTS
+            if (this._eventList.length > MAX_EVENTS) {
+                this._eventList.shift();
+            }
+        }
+    }
+    /**
+     * Updates or adds a closed event to the storage.
+     * Replaces the previous event with the same signalId.
+     *
+     * @param data - Closed tick result
+     */
+    addClosedEvent(data) {
+        const durationMs = data.closeTimestamp - data.signal.timestamp;
+        const durationMin = Math.round(durationMs / 60000);
+        // Find existing event with the same signalId
+        const existingIndex = this._eventList.findIndex((event) => event.signalId === data.signal.id);
+        const newEvent = {
+            timestamp: data.closeTimestamp,
+            action: "closed",
+            symbol: data.signal.symbol,
+            signalId: data.signal.id,
+            position: data.signal.position,
+            note: data.signal.note,
+            currentPrice: data.currentPrice,
+            openPrice: data.signal.priceOpen,
+            takeProfit: data.signal.priceTakeProfit,
+            stopLoss: data.signal.priceStopLoss,
+            pnl: data.pnl.pnlPercentage,
+            closeReason: data.closeReason,
+            duration: durationMin,
+        };
+        // Replace existing event or add new one
+        if (existingIndex !== -1) {
+            this._eventList[existingIndex] = newEvent;
+        }
+        else {
+            this._eventList.push(newEvent);
+            // Trim queue if exceeded MAX_EVENTS
+            if (this._eventList.length > MAX_EVENTS) {
+                this._eventList.shift();
+            }
+        }
+    }
+    /**
+     * Generates markdown report with all tick events for a strategy.
+     *
+     * @param strategyName - Strategy name
+     * @returns Markdown formatted report with all events
+     */
+    getReport(strategyName) {
+        if (this._eventList.length === 0) {
+            return str.newline(`# Live Trading Report: ${strategyName}`, "", "No events recorded yet.");
+        }
+        const header = columns.map((col) => col.label);
+        const rows = this._eventList.map((event) => columns.map((col) => col.format(event)));
+        const tableData = [header, ...rows];
+        const table = str.table(tableData);
+        // Calculate statistics
+        const closedEvents = this._eventList.filter((e) => e.action === "closed");
+        const totalClosed = closedEvents.length;
+        const winCount = closedEvents.filter((e) => e.pnl && e.pnl > 0).length;
+        const lossCount = closedEvents.filter((e) => e.pnl && e.pnl < 0).length;
+        const avgPnl = totalClosed > 0
+            ? closedEvents.reduce((sum, e) => sum + (e.pnl || 0), 0) / totalClosed
+            : 0;
+        return str.newline(`# Live Trading Report: ${strategyName}`, "", `Total events: ${this._eventList.length}`, `Closed signals: ${totalClosed}`, totalClosed > 0
+            ? `Win rate: ${((winCount / totalClosed) * 100).toFixed(2)}% (${winCount}W / ${lossCount}L)`
+            : "", totalClosed > 0
+            ? `Average PNL: ${avgPnl > 0 ? "+" : ""}${avgPnl.toFixed(2)}%`
+            : "", "", table, "", "", `*Generated: ${new Date().toISOString()}*`);
+    }
+    /**
+     * Saves strategy report to disk.
+     *
+     * @param strategyName - Strategy name
+     * @param path - Directory path to save report (default: "./logs/live")
+     */
+    async dump(strategyName, path = "./logs/live") {
+        const markdown = this.getReport(strategyName);
+        try {
+            const dir = join(process.cwd(), path);
+            await mkdir(dir, { recursive: true });
+            const filename = `${strategyName}.md`;
+            const filepath = join(dir, filename);
+            await writeFile(filepath, markdown, "utf-8");
+            console.log(`Live trading report saved: ${filepath}`);
+        }
+        catch (error) {
+            console.error(`Failed to save markdown report:`, error);
+        }
+    }
+}
+/**
+ * Service for generating and saving live trading markdown reports.
+ *
+ * Features:
+ * - Listens to all signal events via onTick callback
+ * - Accumulates all events (idle, opened, active, closed) per strategy
+ * - Generates markdown tables with detailed event information
+ * - Provides trading statistics (win rate, average PNL)
+ * - Saves reports to disk in logs/live/{strategyName}.md
+ *
+ * @example
+ * ```typescript
+ * const service = new LiveMarkdownService();
+ *
+ * // Add to strategy callbacks
+ * addStrategy({
+ *   strategyName: "my-strategy",
+ *   callbacks: {
+ *     onTick: (symbol, result, backtest) => {
+ *       if (!backtest) {
+ *         service.tick(result);
+ *       }
+ *     }
+ *   }
+ * });
+ *
+ * // Later: generate and save report
+ * await service.dump("my-strategy");
+ * ```
+ */
+class LiveMarkdownService {
+    constructor() {
+        /** Logger service for debug output */
+        this.loggerService = inject(TYPES.loggerService);
+        /**
+         * Memoized function to get or create ReportStorage for a strategy.
+         * Each strategy gets its own isolated storage instance.
+         */
+        this.getStorage = memoize(([strategyName]) => `${strategyName}`, () => new ReportStorage());
+        /**
+         * Processes tick events and accumulates all event types.
+         * Should be called from IStrategyCallbacks.onTick.
+         *
+         * Processes all event types: idle, opened, active, closed.
+         *
+         * @param data - Tick result from strategy execution
+         *
+         * @example
+         * ```typescript
+         * const service = new LiveMarkdownService();
+         *
+         * callbacks: {
+         *   onTick: (symbol, result, backtest) => {
+         *     if (!backtest) {
+         *       service.tick(result);
+         *     }
+         *   }
+         * }
+         * ```
+         */
+        this.tick = async (data) => {
+            this.loggerService.log("liveMarkdownService tick", {
+                data,
+            });
+            const storage = this.getStorage(data.strategyName);
+            if (data.action === "idle") {
+                storage.addIdleEvent(data.currentPrice);
+            }
+            else if (data.action === "opened") {
+                storage.addOpenedEvent(data);
+            }
+            else if (data.action === "active") {
+                storage.addActiveEvent(data);
+            }
+            else if (data.action === "closed") {
+                storage.addClosedEvent(data);
+            }
+        };
+        /**
+         * Generates markdown report with all events for a strategy.
+         * Delegates to ReportStorage.getReport().
+         *
+         * @param strategyName - Strategy name to generate report for
+         * @returns Markdown formatted report string with table of all events
+         *
+         * @example
+         * ```typescript
+         * const service = new LiveMarkdownService();
+         * const markdown = await service.getReport("my-strategy");
+         * console.log(markdown);
+         * ```
+         */
+        this.getReport = async (strategyName) => {
+            this.loggerService.log("liveMarkdownService getReport", {
+                strategyName,
+            });
+            const storage = this.getStorage(strategyName);
+            return storage.getReport(strategyName);
+        };
+        /**
+         * Saves strategy report to disk.
+         * Creates directory if it doesn't exist.
+         * Delegates to ReportStorage.dump().
+         *
+         * @param strategyName - Strategy name to save report for
+         * @param path - Directory path to save report (default: "./logs/live")
+         *
+         * @example
+         * ```typescript
+         * const service = new LiveMarkdownService();
+         *
+         * // Save to default path: ./logs/live/my-strategy.md
+         * await service.dump("my-strategy");
+         *
+         * // Save to custom path: ./custom/path/my-strategy.md
+         * await service.dump("my-strategy", "./custom/path");
+         * ```
+         */
+        this.dump = async (strategyName, path = "./logs/live") => {
+            this.loggerService.log("liveMarkdownService dump", {
+                strategyName,
+                path,
+            });
+            const storage = this.getStorage(strategyName);
+            await storage.dump(strategyName, path);
+        };
+        /**
+         * Clears accumulated event data from storage.
+         * If strategyName is provided, clears only that strategy's data.
+         * If strategyName is omitted, clears all strategies' data.
+         *
+         * @param strategyName - Optional strategy name to clear specific strategy data
+         *
+         * @example
+         * ```typescript
+         * const service = new LiveMarkdownService();
+         *
+         * // Clear specific strategy data
+         * await service.clear("my-strategy");
+         *
+         * // Clear all strategies' data
+         * await service.clear();
+         * ```
+         */
+        this.clear = async (strategyName) => {
+            this.loggerService.log("liveMarkdownService clear", {
+                strategyName,
+            });
+            this.getStorage.clear(strategyName);
+        };
+        /**
+         * Initializes the service by subscribing to live signal events.
+         * Uses singleshot to ensure initialization happens only once.
+         * Automatically called on first use.
+         *
+         * @example
+         * ```typescript
+         * const service = new LiveMarkdownService();
+         * await service.init(); // Subscribe to live events
+         * ```
+         */
+        this.init = singleshot(async () => {
+            this.loggerService.log("liveMarkdownService init");
+            signalLiveEmitter.subscribe(this.tick);
+        });
+    }
+}
+
+/**
+ * @class ExchangeValidationService
+ * Service for managing and validating exchange configurations
+ */
+class ExchangeValidationService {
+    constructor() {
+        /**
+         * @private
+         * @readonly
+         * Injected logger service instance
+         */
+        this.loggerService = inject(TYPES.loggerService);
+        /**
+         * @private
+         * Map storing exchange schemas by exchange name
+         */
+        this._exchangeMap = new Map();
+        /**
+         * Adds an exchange schema to the validation service
+         * @public
+         * @throws {Error} If exchangeName already exists
+         */
+        this.addExchange = (exchangeName, exchangeSchema) => {
+            this.loggerService.log("exchangeValidationService addExchange", {
+                exchangeName,
+                exchangeSchema,
+            });
+            if (this._exchangeMap.has(exchangeName)) {
+                throw new Error(`exchange ${exchangeName} already exist`);
+            }
+            this._exchangeMap.set(exchangeName, exchangeSchema);
+        };
+        /**
+         * Validates the existence of an exchange
+         * @public
+         * @throws {Error} If exchangeName is not found
+         * Memoized function to cache validation results
+         */
+        this.validate = memoize(([exchangeName]) => exchangeName, (exchangeName, source) => {
+            this.loggerService.log("exchangeValidationService validate", {
+                exchangeName,
+                source,
+            });
+            const exchange = this._exchangeMap.get(exchangeName);
+            if (!exchange) {
+                throw new Error(`exchange ${exchangeName} not found source=${source}`);
+            }
+            return true;
+        });
+    }
+}
+
+/**
+ * @class StrategyValidationService
+ * Service for managing and validating strategy configurations
+ */
+class StrategyValidationService {
+    constructor() {
+        /**
+         * @private
+         * @readonly
+         * Injected logger service instance
+         */
+        this.loggerService = inject(TYPES.loggerService);
+        /**
+         * @private
+         * Map storing strategy schemas by strategy name
+         */
+        this._strategyMap = new Map();
+        /**
+         * Adds a strategy schema to the validation service
+         * @public
+         * @throws {Error} If strategyName already exists
+         */
+        this.addStrategy = (strategyName, strategySchema) => {
+            this.loggerService.log("strategyValidationService addStrategy", {
+                strategyName,
+                strategySchema,
+            });
+            if (this._strategyMap.has(strategyName)) {
+                throw new Error(`strategy ${strategyName} already exist`);
+            }
+            this._strategyMap.set(strategyName, strategySchema);
+        };
+        /**
+         * Validates the existence of a strategy
+         * @public
+         * @throws {Error} If strategyName is not found
+         * Memoized function to cache validation results
+         */
+        this.validate = memoize(([strategyName]) => strategyName, (strategyName, source) => {
+            this.loggerService.log("strategyValidationService validate", {
+                strategyName,
+                source,
+            });
+            const strategy = this._strategyMap.get(strategyName);
+            if (!strategy) {
+                throw new Error(`strategy ${strategyName} not found source=${source}`);
+            }
+            return true;
+        });
+    }
+}
+
+/**
+ * @class FrameValidationService
+ * Service for managing and validating frame configurations
+ */
+class FrameValidationService {
+    constructor() {
+        /**
+         * @private
+         * @readonly
+         * Injected logger service instance
+         */
+        this.loggerService = inject(TYPES.loggerService);
+        /**
+         * @private
+         * Map storing frame schemas by frame name
+         */
+        this._frameMap = new Map();
+        /**
+         * Adds a frame schema to the validation service
+         * @public
+         * @throws {Error} If frameName already exists
+         */
+        this.addFrame = (frameName, frameSchema) => {
+            this.loggerService.log("frameValidationService addFrame", {
+                frameName,
+                frameSchema,
+            });
+            if (this._frameMap.has(frameName)) {
+                throw new Error(`frame ${frameName} already exist`);
+            }
+            this._frameMap.set(frameName, frameSchema);
+        };
+        /**
+         * Validates the existence of a frame
+         * @public
+         * @throws {Error} If frameName is not found
+         * Memoized function to cache validation results
+         */
+        this.validate = memoize(([frameName]) => frameName, (frameName, source) => {
+            this.loggerService.log("frameValidationService validate", {
+                frameName,
+                source,
+            });
+            const frame = this._frameMap.get(frameName);
+            if (!frame) {
+                throw new Error(`frame ${frameName} not found source=${source}`);
+            }
+            return true;
+        });
+    }
+}
+
+{
+    provide(TYPES.loggerService, () => new LoggerService());
+}
+{
+    provide(TYPES.executionContextService, () => new ExecutionContextService());
+    provide(TYPES.methodContextService, () => new MethodContextService());
+}
+{
+    provide(TYPES.exchangeConnectionService, () => new ExchangeConnectionService());
+    provide(TYPES.strategyConnectionService, () => new StrategyConnectionService());
+    provide(TYPES.frameConnectionService, () => new FrameConnectionService());
+}
+{
+    provide(TYPES.exchangeSchemaService, () => new ExchangeSchemaService());
+    provide(TYPES.strategySchemaService, () => new StrategySchemaService());
+    provide(TYPES.frameSchemaService, () => new FrameSchemaService());
+}
+{
+    provide(TYPES.exchangeGlobalService, () => new ExchangeGlobalService());
+    provide(TYPES.strategyGlobalService, () => new StrategyGlobalService());
+    provide(TYPES.frameGlobalService, () => new FrameGlobalService());
+    provide(TYPES.liveGlobalService, () => new LiveGlobalService());
+    provide(TYPES.backtestGlobalService, () => new BacktestGlobalService());
+}
+{
+    provide(TYPES.backtestLogicPrivateService, () => new BacktestLogicPrivateService());
+    provide(TYPES.liveLogicPrivateService, () => new LiveLogicPrivateService());
+}
+{
+    provide(TYPES.backtestLogicPublicService, () => new BacktestLogicPublicService());
+    provide(TYPES.liveLogicPublicService, () => new LiveLogicPublicService());
+}
+{
+    provide(TYPES.backtestMarkdownService, () => new BacktestMarkdownService());
+    provide(TYPES.liveMarkdownService, () => new LiveMarkdownService());
+}
+{
+    provide(TYPES.exchangeValidationService, () => new ExchangeValidationService());
+    provide(TYPES.strategyValidationService, () => new StrategyValidationService());
+    provide(TYPES.frameValidationService, () => new FrameValidationService());
+}
+
+const baseServices = {
+    loggerService: inject(TYPES.loggerService),
+};
+const contextServices = {
+    executionContextService: inject(TYPES.executionContextService),
+    methodContextService: inject(TYPES.methodContextService),
+};
+const connectionServices = {
+    exchangeConnectionService: inject(TYPES.exchangeConnectionService),
+    strategyConnectionService: inject(TYPES.strategyConnectionService),
+    frameConnectionService: inject(TYPES.frameConnectionService),
 };
 const schemaServices = {
     exchangeSchemaService: inject(TYPES.exchangeSchemaService),
@@ -1419,6 +3547,15 @@ const logicPublicServices = {
     backtestLogicPublicService: inject(TYPES.backtestLogicPublicService),
     liveLogicPublicService: inject(TYPES.liveLogicPublicService),
 };
+const markdownServices = {
+    backtestMarkdownService: inject(TYPES.backtestMarkdownService),
+    liveMarkdownService: inject(TYPES.liveMarkdownService),
+};
+const validationServices = {
+    exchangeValidationService: inject(TYPES.exchangeValidationService),
+    strategyValidationService: inject(TYPES.strategyValidationService),
+    frameValidationService: inject(TYPES.frameValidationService),
+};
 const backtest = {
     ...baseServices,
     ...contextServices,
@@ -1427,10 +3564,29 @@ const backtest = {
     ...globalServices,
     ...logicPrivateServices,
     ...logicPublicServices,
+    ...markdownServices,
+    ...validationServices,
 };
 init();
 var backtest$1 = backtest;
 
+/**
+ * Sets custom logger implementation for the framework.
+ *
+ * All log messages from internal services will be forwarded to the provided logger
+ * with automatic context injection (strategyName, exchangeName, symbol, etc.).
+ *
+ * @param logger - Custom logger implementing ILogger interface
+ *
+ * @example
+ * ```typescript
+ * setLogger({
+ *   log: (topic, ...args) => console.log(topic, args),
+ *   debug: (topic, ...args) => console.debug(topic, args),
+ *   info: (topic, ...args) => console.info(topic, args),
+ * });
+ * ```
+ */
 async function setLogger(logger) {
     backtest$1.loggerService.setLogger(logger);
 }
@@ -1438,136 +3594,323 @@ async function setLogger(logger) {
 const ADD_STRATEGY_METHOD_NAME = "add.addStrategy";
 const ADD_EXCHANGE_METHOD_NAME = "add.addExchange";
 const ADD_FRAME_METHOD_NAME = "add.addFrame";
+/**
+ * Registers a trading strategy in the framework.
+ *
+ * The strategy will be validated for:
+ * - Signal validation (prices, TP/SL logic, timestamps)
+ * - Interval throttling (prevents signal spam)
+ * - Crash-safe persistence in live mode
+ *
+ * @param strategySchema - Strategy configuration object
+ * @param strategySchema.strategyName - Unique strategy identifier
+ * @param strategySchema.interval - Signal generation interval ("1m" | "3m" | "5m" | "15m" | "30m" | "1h")
+ * @param strategySchema.getSignal - Async function that generates trading signals
+ * @param strategySchema.callbacks - Optional lifecycle callbacks (onOpen, onClose)
+ *
+ * @example
+ * ```typescript
+ * addStrategy({
+ *   strategyName: "my-strategy",
+ *   interval: "5m",
+ *   getSignal: async (symbol) => ({
+ *     position: "long",
+ *     priceOpen: 50000,
+ *     priceTakeProfit: 51000,
+ *     priceStopLoss: 49000,
+ *     minuteEstimatedTime: 60,
+ *     timestamp: Date.now(),
+ *   }),
+ *   callbacks: {
+ *     onOpen: (backtest, symbol, signal) => console.log("Signal opened"),
+ *     onClose: (backtest, symbol, priceClose, signal) => console.log("Signal closed"),
+ *   },
+ * });
+ * ```
+ */
 function addStrategy(strategySchema) {
     backtest$1.loggerService.info(ADD_STRATEGY_METHOD_NAME, {
         strategySchema,
     });
+    backtest$1.strategyValidationService.addStrategy(strategySchema.strategyName, strategySchema);
     backtest$1.strategySchemaService.register(strategySchema.strategyName, strategySchema);
 }
+/**
+ * Registers an exchange data source in the framework.
+ *
+ * The exchange provides:
+ * - Historical candle data via getCandles
+ * - Price/quantity formatting for the exchange
+ * - VWAP calculation from last 5 1m candles
+ *
+ * @param exchangeSchema - Exchange configuration object
+ * @param exchangeSchema.exchangeName - Unique exchange identifier
+ * @param exchangeSchema.getCandles - Async function to fetch candle data
+ * @param exchangeSchema.formatPrice - Async function to format prices
+ * @param exchangeSchema.formatQuantity - Async function to format quantities
+ * @param exchangeSchema.callbacks - Optional callback for candle data events
+ *
+ * @example
+ * ```typescript
+ * addExchange({
+ *   exchangeName: "binance",
+ *   getCandles: async (symbol, interval, since, limit) => {
+ *     // Fetch from Binance API or database
+ *     return [{
+ *       timestamp: Date.now(),
+ *       open: 50000,
+ *       high: 51000,
+ *       low: 49000,
+ *       close: 50500,
+ *       volume: 1000,
+ *     }];
+ *   },
+ *   formatPrice: async (symbol, price) => price.toFixed(2),
+ *   formatQuantity: async (symbol, quantity) => quantity.toFixed(8),
+ * });
+ * ```
+ */
 function addExchange(exchangeSchema) {
     backtest$1.loggerService.info(ADD_EXCHANGE_METHOD_NAME, {
         exchangeSchema,
     });
+    backtest$1.exchangeValidationService.addExchange(exchangeSchema.exchangeName, exchangeSchema);
     backtest$1.exchangeSchemaService.register(exchangeSchema.exchangeName, exchangeSchema);
 }
+/**
+ * Registers a timeframe generator for backtesting.
+ *
+ * The frame defines:
+ * - Start and end dates for backtest period
+ * - Interval for timeframe generation
+ * - Callback for timeframe generation events
+ *
+ * @param frameSchema - Frame configuration object
+ * @param frameSchema.frameName - Unique frame identifier
+ * @param frameSchema.interval - Timeframe interval ("1m" | "3m" | "5m" | "15m" | "30m" | "1h" | "2h" | "4h" | "6h" | "8h" | "12h" | "1d" | "3d")
+ * @param frameSchema.startDate - Start date for timeframe generation
+ * @param frameSchema.endDate - End date for timeframe generation
+ * @param frameSchema.callbacks - Optional callback for timeframe events
+ *
+ * @example
+ * ```typescript
+ * addFrame({
+ *   frameName: "1d-backtest",
+ *   interval: "1m",
+ *   startDate: new Date("2024-01-01T00:00:00Z"),
+ *   endDate: new Date("2024-01-02T00:00:00Z"),
+ *   callbacks: {
+ *     onTimeframe: (timeframe, startDate, endDate, interval) => {
+ *       console.log(`Generated ${timeframe.length} timeframes`);
+ *     },
+ *   },
+ * });
+ * ```
+ */
 function addFrame(frameSchema) {
     backtest$1.loggerService.info(ADD_FRAME_METHOD_NAME, {
         frameSchema,
     });
+    backtest$1.frameValidationService.addFrame(frameSchema.frameName, frameSchema);
     backtest$1.frameSchemaService.register(frameSchema.frameName, frameSchema);
 }
 
-async function runBacktest(symbol, timeframes) {
-    const results = [];
-    for (const when of timeframes) {
-        const result = await backtest$1.strategyGlobalService.tick(symbol, when, true);
-        // Сохраняем только результаты closed
-        if (result.action === "closed") {
-            results.push(result);
-        }
-    }
-    return {
-        symbol,
-        results,
-    };
+const LISTEN_SIGNAL_METHOD_NAME = "event.listenSignal";
+const LISTEN_SIGNAL_ONCE_METHOD_NAME = "event.listenSignalOnce";
+const LISTEN_SIGNAL_LIVE_METHOD_NAME = "event.listenSignalLive";
+const LISTEN_SIGNAL_LIVE_ONCE_METHOD_NAME = "event.listenSignalLiveOnce";
+const LISTEN_SIGNAL_BACKTEST_METHOD_NAME = "event.listenSignalBacktest";
+const LISTEN_SIGNAL_BACKTEST_ONCE_METHOD_NAME = "event.listenSignalBacktestOnce";
+const LISTEN_ERROR_METHOD_NAME = "event.listenError";
+/**
+ * Subscribes to all signal events with queued async processing.
+ *
+ * Events are processed sequentially in order received, even if callback is async.
+ * Uses queued wrapper to prevent concurrent execution of the callback.
+ *
+ * @param fn - Callback function to handle signal events (idle, opened, active, closed)
+ * @returns Unsubscribe function to stop listening
+ *
+ * @example
+ * ```typescript
+ * import { listenSignal } from "./function/event";
+ *
+ * const unsubscribe = listenSignal((event) => {
+ *   if (event.action === "opened") {
+ *     console.log("New signal opened:", event.signal);
+ *   } else if (event.action === "closed") {
+ *     console.log("Signal closed with PNL:", event.pnl.pnlPercentage);
+ *   }
+ * });
+ *
+ * // Later: stop listening
+ * unsubscribe();
+ * ```
+ */
+function listenSignal(fn) {
+    backtest$1.loggerService.log(LISTEN_SIGNAL_METHOD_NAME);
+    return signalEmitter.subscribe(queued(async (event) => fn(event)));
 }
-async function runBacktestGUI(symbol, timeframes) {
-    const backtestResult = await runBacktest(symbol, timeframes);
-    const { results } = backtestResult;
-    // Таблица для терминала
-    const table = new Table({
-        head: ["#", "Time", "Note", "Price", "Reason", "PNL %"],
-    });
-    let totalPnl = 0;
-    let winCount = 0;
-    let lossCount = 0;
-    results.forEach((result, index) => {
-        if (result.action === "closed") {
-            const pnl = result.pnl.pnlPercentage;
-            totalPnl += pnl;
-            if (pnl > 0)
-                winCount++;
-            else if (pnl < 0)
-                lossCount++;
-            const pnlFormatted = pnl > 0 ? `+${pnl.toFixed(2)}%` : `${pnl.toFixed(2)}%`;
-            const emoji = pnl > 0 ? "🟢" : pnl < 0 ? "🔴" : "⚪";
-            table.push([
-                index + 1,
-                new Date(result.signal.timestamp).toISOString(),
-                result.signal.note,
-                result.currentPrice.toFixed(2),
-                result.closeReason,
-                `${emoji} ${pnlFormatted}`,
-            ]);
-        }
-    });
-    // Добавляем статистику
-    const closedCount = results.length;
-    table.push([]);
-    table.push([
-        "TOTAL",
-        `${closedCount} trades`,
-        `Win: ${winCount}`,
-        `Loss: ${lossCount}`,
-        "-",
-        `WR: ${closedCount > 0 ? ((winCount / closedCount) * 100).toFixed(1) : 0}%`,
-        `${totalPnl > 0 ? "+" : ""}${totalPnl.toFixed(2)}%`,
-    ]);
-    console.log("\n");
-    console.log(table.toString());
-    console.log("\n");
+/**
+ * Subscribes to filtered signal events with one-time execution.
+ *
+ * Listens for events matching the filter predicate, then executes callback once
+ * and automatically unsubscribes. Useful for waiting for specific signal conditions.
+ *
+ * @param filterFn - Predicate to filter which events trigger the callback
+ * @param fn - Callback function to handle the filtered event (called only once)
+ * @returns Unsubscribe function to cancel the listener before it fires
+ *
+ * @example
+ * ```typescript
+ * import { listenSignalOnce } from "./function/event";
+ *
+ * // Wait for first take profit hit
+ * listenSignalOnce(
+ *   (event) => event.action === "closed" && event.closeReason === "take_profit",
+ *   (event) => {
+ *     console.log("Take profit hit! PNL:", event.pnl.pnlPercentage);
+ *   }
+ * );
+ *
+ * // Wait for any signal to close on BTCUSDT
+ * const cancel = listenSignalOnce(
+ *   (event) => event.action === "closed" && event.signal.symbol === "BTCUSDT",
+ *   (event) => console.log("BTCUSDT signal closed")
+ * );
+ *
+ * // Cancel if needed before event fires
+ * cancel();
+ * ```
+ */
+function listenSignalOnce(filterFn, fn) {
+    backtest$1.loggerService.log(LISTEN_SIGNAL_ONCE_METHOD_NAME);
+    return signalEmitter.filter(filterFn).once(fn);
 }
-
-async function reduce(symbol, timeframes, callback, initialValue) {
-    let accumulator = initialValue;
-    for (let i = 0; i < timeframes.length; i++) {
-        const when = timeframes[i];
-        accumulator = await callback(accumulator, i, when, symbol);
-    }
-    return {
-        symbol,
-        accumulator,
-        totalTicks: timeframes.length,
-    };
+/**
+ * Subscribes to live trading signal events with queued async processing.
+ *
+ * Only receives events from Live.run() execution.
+ * Events are processed sequentially in order received.
+ *
+ * @param fn - Callback function to handle live signal events
+ * @returns Unsubscribe function to stop listening
+ *
+ * @example
+ * ```typescript
+ * import { listenSignalLive } from "./function/event";
+ *
+ * const unsubscribe = listenSignalLive((event) => {
+ *   if (event.action === "closed") {
+ *     console.log("Live signal closed:", event.pnl.pnlPercentage);
+ *   }
+ * });
+ * ```
+ */
+function listenSignalLive(fn) {
+    backtest$1.loggerService.log(LISTEN_SIGNAL_LIVE_METHOD_NAME);
+    return signalLiveEmitter.subscribe(queued(async (event) => fn(event)));
 }
-
-const instances = new Map();
-function startRun(config) {
-    const { symbol, interval } = config;
-    // Останавливаем предыдущий инстанс для этого символа
-    if (instances.has(symbol)) {
-        stopRun(symbol);
-    }
-    const doWork = singlerun(async () => {
-        const now = new Date();
-        const result = await backtest$1.strategyGlobalService.tick(symbol, now, false);
-        const instance = instances.get(symbol);
-        if (instance) {
-            instance.tickCount++;
-        }
-        await sleep(interval);
-        return result;
-    });
-    const intervalId = setInterval(doWork, interval);
-    instances.set(symbol, {
-        config,
-        tickCount: 0,
-        intervalId,
-        doWork,
-    });
+/**
+ * Subscribes to filtered live signal events with one-time execution.
+ *
+ * Only receives events from Live.run() execution.
+ * Executes callback once and automatically unsubscribes.
+ *
+ * @param filterFn - Predicate to filter which events trigger the callback
+ * @param fn - Callback function to handle the filtered event (called only once)
+ * @returns Unsubscribe function to cancel the listener before it fires
+ *
+ * @example
+ * ```typescript
+ * import { listenSignalLiveOnce } from "./function/event";
+ *
+ * // Wait for first live take profit hit
+ * listenSignalLiveOnce(
+ *   (event) => event.action === "closed" && event.closeReason === "take_profit",
+ *   (event) => console.log("Live take profit:", event.pnl.pnlPercentage)
+ * );
+ * ```
+ */
+function listenSignalLiveOnce(filterFn, fn) {
+    backtest$1.loggerService.log(LISTEN_SIGNAL_LIVE_ONCE_METHOD_NAME);
+    return signalLiveEmitter.filter(filterFn).once(fn);
 }
-function stopRun(symbol) {
-    const instance = instances.get(symbol);
-    if (instance) {
-        clearInterval(instance.intervalId);
-        instances.delete(symbol);
-    }
+/**
+ * Subscribes to backtest signal events with queued async processing.
+ *
+ * Only receives events from Backtest.run() execution.
+ * Events are processed sequentially in order received.
+ *
+ * @param fn - Callback function to handle backtest signal events
+ * @returns Unsubscribe function to stop listening
+ *
+ * @example
+ * ```typescript
+ * import { listenSignalBacktest } from "./function/event";
+ *
+ * const unsubscribe = listenSignalBacktest((event) => {
+ *   if (event.action === "closed") {
+ *     console.log("Backtest signal closed:", event.pnl.pnlPercentage);
+ *   }
+ * });
+ * ```
+ */
+function listenSignalBacktest(fn) {
+    backtest$1.loggerService.log(LISTEN_SIGNAL_BACKTEST_METHOD_NAME);
+    return signalBacktestEmitter.subscribe(queued(async (event) => fn(event)));
 }
-function stopAll() {
-    instances.forEach((instance) => {
-        clearInterval(instance.intervalId);
-    });
-    instances.clear();
+/**
+ * Subscribes to filtered backtest signal events with one-time execution.
+ *
+ * Only receives events from Backtest.run() execution.
+ * Executes callback once and automatically unsubscribes.
+ *
+ * @param filterFn - Predicate to filter which events trigger the callback
+ * @param fn - Callback function to handle the filtered event (called only once)
+ * @returns Unsubscribe function to cancel the listener before it fires
+ *
+ * @example
+ * ```typescript
+ * import { listenSignalBacktestOnce } from "./function/event";
+ *
+ * // Wait for first backtest stop loss hit
+ * listenSignalBacktestOnce(
+ *   (event) => event.action === "closed" && event.closeReason === "stop_loss",
+ *   (event) => console.log("Backtest stop loss:", event.pnl.pnlPercentage)
+ * );
+ * ```
+ */
+function listenSignalBacktestOnce(filterFn, fn) {
+    backtest$1.loggerService.log(LISTEN_SIGNAL_BACKTEST_ONCE_METHOD_NAME);
+    return signalBacktestEmitter.filter(filterFn).once(fn);
+}
+/**
+ * Subscribes to background execution errors with queued async processing.
+ *
+ * Listens to errors caught in Live.background() and Backtest.background() execution.
+ * Events are processed sequentially in order received, even if callback is async.
+ * Uses queued wrapper to prevent concurrent execution of the callback.
+ *
+ * @param fn - Callback function to handle error events
+ * @returns Unsubscribe function to stop listening
+ *
+ * @example
+ * ```typescript
+ * import { listenError } from "./function/event";
+ *
+ * const unsubscribe = listenError((error) => {
+ *   console.error("Background execution error:", error.message);
+ *   // Log to monitoring service, send alerts, etc.
+ * });
+ *
+ * // Later: stop listening
+ * unsubscribe();
+ * ```
+ */
+function listenError(fn) {
+    backtest$1.loggerService.log(LISTEN_ERROR_METHOD_NAME);
+    return errorEmitter.subscribe(queued(async (error) => fn(error)));
 }
 
 const GET_CANDLES_METHOD_NAME = "exchange.getCandles";
@@ -1576,6 +3919,23 @@ const FORMAT_PRICE_METHOD_NAME = "exchange.formatPrice";
 const FORMAT_QUANTITY_METHOD_NAME = "exchange.formatQuantity";
 const GET_DATE_METHOD_NAME = "exchange.getDate";
 const GET_MODE_METHOD_NAME = "exchange.getMode";
+/**
+ * Fetches historical candle data from the registered exchange.
+ *
+ * Candles are fetched backwards from the current execution context time.
+ * Uses the exchange's getCandles implementation.
+ *
+ * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+ * @param interval - Candle interval ("1m" | "3m" | "5m" | "15m" | "30m" | "1h" | "2h" | "4h" | "6h" | "8h")
+ * @param limit - Number of candles to fetch
+ * @returns Promise resolving to array of candle data
+ *
+ * @example
+ * ```typescript
+ * const candles = await getCandles("BTCUSDT", "1m", 100);
+ * console.log(candles[0]); // { timestamp, open, high, low, close, volume }
+ * ```
+ */
 async function getCandles(symbol, interval, limit) {
     backtest$1.loggerService.info(GET_CANDLES_METHOD_NAME, {
         symbol,
@@ -1584,12 +3944,45 @@ async function getCandles(symbol, interval, limit) {
     });
     return await backtest$1.exchangeConnectionService.getCandles(symbol, interval, limit);
 }
+/**
+ * Calculates VWAP (Volume Weighted Average Price) for a symbol.
+ *
+ * Uses the last 5 1-minute candles to calculate:
+ * - Typical Price = (high + low + close) / 3
+ * - VWAP = sum(typical_price * volume) / sum(volume)
+ *
+ * If volume is zero, returns simple average of close prices.
+ *
+ * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+ * @returns Promise resolving to VWAP price
+ *
+ * @example
+ * ```typescript
+ * const vwap = await getAveragePrice("BTCUSDT");
+ * console.log(vwap); // 50125.43
+ * ```
+ */
 async function getAveragePrice(symbol) {
     backtest$1.loggerService.info(GET_AVERAGE_PRICE_METHOD_NAME, {
         symbol,
     });
     return await backtest$1.exchangeConnectionService.getAveragePrice(symbol);
 }
+/**
+ * Formats a price value according to exchange rules.
+ *
+ * Uses the exchange's formatPrice implementation for proper decimal places.
+ *
+ * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+ * @param price - Raw price value
+ * @returns Promise resolving to formatted price string
+ *
+ * @example
+ * ```typescript
+ * const formatted = await formatPrice("BTCUSDT", 50000.123456);
+ * console.log(formatted); // "50000.12"
+ * ```
+ */
 async function formatPrice(symbol, price) {
     backtest$1.loggerService.info(FORMAT_PRICE_METHOD_NAME, {
         symbol,
@@ -1597,6 +3990,21 @@ async function formatPrice(symbol, price) {
     });
     return await backtest$1.exchangeConnectionService.formatPrice(symbol, price);
 }
+/**
+ * Formats a quantity value according to exchange rules.
+ *
+ * Uses the exchange's formatQuantity implementation for proper decimal places.
+ *
+ * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+ * @param quantity - Raw quantity value
+ * @returns Promise resolving to formatted quantity string
+ *
+ * @example
+ * ```typescript
+ * const formatted = await formatQuantity("BTCUSDT", 0.123456789);
+ * console.log(formatted); // "0.12345678"
+ * ```
+ */
 async function formatQuantity(symbol, quantity) {
     backtest$1.loggerService.info(FORMAT_QUANTITY_METHOD_NAME, {
         symbol,
@@ -1604,11 +4012,40 @@ async function formatQuantity(symbol, quantity) {
     });
     return await backtest$1.exchangeConnectionService.formatQuantity(symbol, quantity);
 }
+/**
+ * Gets the current date from execution context.
+ *
+ * In backtest mode: returns the current timeframe date being processed
+ * In live mode: returns current real-time date
+ *
+ * @returns Promise resolving to current execution context date
+ *
+ * @example
+ * ```typescript
+ * const date = await getDate();
+ * console.log(date); // 2024-01-01T12:00:00.000Z
+ * ```
+ */
 async function getDate() {
     backtest$1.loggerService.info(GET_DATE_METHOD_NAME);
     const { when } = backtest$1.executionContextService.context;
     return new Date(when.getTime());
 }
+/**
+ * Gets the current execution mode.
+ *
+ * @returns Promise resolving to "backtest" or "live"
+ *
+ * @example
+ * ```typescript
+ * const mode = await getMode();
+ * if (mode === "backtest") {
+ *   console.log("Running in backtest mode");
+ * } else {
+ *   console.log("Running in live mode");
+ * }
+ * ```
+ */
 async function getMode() {
     backtest$1.loggerService.info(GET_MODE_METHOD_NAME);
     const { backtest: bt } = backtest$1.executionContextService.context;
@@ -1616,8 +4053,37 @@ async function getMode() {
 }
 
 const BACKTEST_METHOD_NAME_RUN = "BacktestUtils.run";
+const BACKTEST_METHOD_NAME_BACKGROUND = "BacktestUtils.background";
+const BACKTEST_METHOD_NAME_GET_REPORT = "BacktestUtils.getReport";
+const BACKTEST_METHOD_NAME_DUMP = "BacktestUtils.dump";
+/**
+ * Utility class for backtest operations.
+ *
+ * Provides simplified access to backtestGlobalService.run() with logging.
+ * Exported as singleton instance for convenient usage.
+ *
+ * @example
+ * ```typescript
+ * import { Backtest } from "./classes/Backtest";
+ *
+ * for await (const result of Backtest.run("BTCUSDT", {
+ *   strategyName: "my-strategy",
+ *   exchangeName: "my-exchange",
+ *   frameName: "1d-backtest"
+ * })) {
+ *   console.log("Closed signal PNL:", result.pnl.pnlPercentage);
+ * }
+ * ```
+ */
 class BacktestUtils {
     constructor() {
+        /**
+         * Runs backtest for a symbol with context propagation.
+         *
+         * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+         * @param context - Execution context with strategy, exchange, and frame names
+         * @returns Async generator yielding closed signals with PNL
+         */
         this.run = (symbol, context) => {
             backtest$1.loggerService.info(BACKTEST_METHOD_NAME_RUN, {
                 symbol,
@@ -1625,13 +4091,157 @@ class BacktestUtils {
             });
             return backtest$1.backtestGlobalService.run(symbol, context);
         };
+        /**
+         * Runs backtest in background without yielding results.
+         *
+         * Consumes all backtest results internally without exposing them.
+         * Useful for running backtests for side effects only (callbacks, logging).
+         *
+         * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+         * @param context - Execution context with strategy, exchange, and frame names
+         * @returns Cancellation closure
+         *
+         * @example
+         * ```typescript
+         * // Run backtest silently, only callbacks will fire
+         * await Backtest.background("BTCUSDT", {
+         *   strategyName: "my-strategy",
+         *   exchangeName: "my-exchange",
+         *   frameName: "1d-backtest"
+         * });
+         * console.log("Backtest completed");
+         * ```
+         */
+        this.background = async (symbol, context) => {
+            backtest$1.loggerService.info(BACKTEST_METHOD_NAME_BACKGROUND, {
+                symbol,
+                context,
+            });
+            const iterator = this.run(symbol, context);
+            let isStopped = false;
+            const task = async () => {
+                while (true) {
+                    const { done } = await iterator.next();
+                    if (done) {
+                        break;
+                    }
+                    if (isStopped) {
+                        break;
+                    }
+                }
+            };
+            task().catch((error) => errorEmitter.next(new Error(getErrorMessage(error))));
+            return () => {
+                isStopped = true;
+            };
+        };
+        /**
+         * Generates markdown report with all closed signals for a strategy.
+         *
+         * @param strategyName - Strategy name to generate report for
+         * @returns Promise resolving to markdown formatted report string
+         *
+         * @example
+         * ```typescript
+         * const markdown = await Backtest.getReport("my-strategy");
+         * console.log(markdown);
+         * ```
+         */
+        this.getReport = async (strategyName) => {
+            backtest$1.loggerService.info(BACKTEST_METHOD_NAME_GET_REPORT, {
+                strategyName,
+            });
+            return await backtest$1.backtestMarkdownService.getReport(strategyName);
+        };
+        /**
+         * Saves strategy report to disk.
+         *
+         * @param strategyName - Strategy name to save report for
+         * @param path - Optional directory path to save report (default: "./logs/backtest")
+         *
+         * @example
+         * ```typescript
+         * // Save to default path: ./logs/backtest/my-strategy.md
+         * await Backtest.dump("my-strategy");
+         *
+         * // Save to custom path: ./custom/path/my-strategy.md
+         * await Backtest.dump("my-strategy", "./custom/path");
+         * ```
+         */
+        this.dump = async (strategyName, path) => {
+            backtest$1.loggerService.info(BACKTEST_METHOD_NAME_DUMP, {
+                strategyName,
+                path,
+            });
+            await backtest$1.backtestMarkdownService.dump(strategyName, path);
+        };
     }
 }
+/**
+ * Singleton instance of BacktestUtils for convenient backtest operations.
+ *
+ * @example
+ * ```typescript
+ * import { Backtest } from "./classes/Backtest";
+ *
+ * for await (const result of Backtest.run("BTCUSDT", {
+ *   strategyName: "my-strategy",
+ *   exchangeName: "my-exchange",
+ *   frameName: "1d-backtest"
+ * })) {
+ *   if (result.action === "closed") {
+ *     console.log("PNL:", result.pnl.pnlPercentage);
+ *   }
+ * }
+ * ```
+ */
 const Backtest = new BacktestUtils();
 
 const LIVE_METHOD_NAME_RUN = "LiveUtils.run";
+const LIVE_METHOD_NAME_BACKGROUND = "LiveUtils.background";
+const LIVE_METHOD_NAME_GET_REPORT = "LiveUtils.getReport";
+const LIVE_METHOD_NAME_DUMP = "LiveUtils.dump";
+/**
+ * Utility class for live trading operations.
+ *
+ * Provides simplified access to liveGlobalService.run() with logging.
+ * Exported as singleton instance for convenient usage.
+ *
+ * Features:
+ * - Infinite async generator (never completes)
+ * - Crash recovery via persisted state
+ * - Real-time progression with Date.now()
+ *
+ * @example
+ * ```typescript
+ * import { Live } from "./classes/Live";
+ *
+ * // Infinite loop - use Ctrl+C to stop
+ * for await (const result of Live.run("BTCUSDT", {
+ *   strategyName: "my-strategy",
+ *   exchangeName: "my-exchange",
+ *   frameName: ""
+ * })) {
+ *   if (result.action === "opened") {
+ *     console.log("Signal opened:", result.signal);
+ *   } else if (result.action === "closed") {
+ *     console.log("PNL:", result.pnl.pnlPercentage);
+ *   }
+ * }
+ * ```
+ */
 class LiveUtils {
     constructor() {
+        /**
+         * Runs live trading for a symbol with context propagation.
+         *
+         * Infinite async generator with crash recovery support.
+         * Process can crash and restart - state will be recovered from disk.
+         *
+         * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+         * @param context - Execution context with strategy and exchange names
+         * @returns Infinite async generator yielding opened and closed signals
+         */
         this.run = (symbol, context) => {
             backtest$1.loggerService.info(LIVE_METHOD_NAME_RUN, {
                 symbol,
@@ -1639,8 +4249,111 @@ class LiveUtils {
             });
             return backtest$1.liveGlobalService.run(symbol, context);
         };
+        /**
+         * Runs live trading in background without yielding results.
+         *
+         * Consumes all live trading results internally without exposing them.
+         * Infinite loop - will run until process is stopped or crashes.
+         * Useful for running live trading for side effects only (callbacks, persistence).
+         *
+         * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+         * @param context - Execution context with strategy and exchange names
+         * @returns Cancellation closure
+         *
+         * @example
+         * ```typescript
+         * // Run live trading silently in background, only callbacks will fire
+         * // This will run forever until Ctrl+C
+         * await Live.background("BTCUSDT", {
+         *   strategyName: "my-strategy",
+         *   exchangeName: "my-exchange"
+         * });
+         * ```
+         */
+        this.background = async (symbol, context) => {
+            backtest$1.loggerService.info(LIVE_METHOD_NAME_BACKGROUND, {
+                symbol,
+                context,
+            });
+            const iterator = this.run(symbol, context);
+            let isStopped = false;
+            let lastValue = null;
+            const task = async () => {
+                while (true) {
+                    const { value, done } = await iterator.next();
+                    if (value) {
+                        lastValue = value;
+                    }
+                    if (done) {
+                        break;
+                    }
+                    if (lastValue?.action === "closed" && isStopped) {
+                        break;
+                    }
+                }
+            };
+            task().catch((error) => errorEmitter.next(new Error(getErrorMessage(error))));
+            return () => {
+                isStopped = true;
+            };
+        };
+        /**
+         * Generates markdown report with all events for a strategy.
+         *
+         * @param strategyName - Strategy name to generate report for
+         * @returns Promise resolving to markdown formatted report string
+         *
+         * @example
+         * ```typescript
+         * const markdown = await Live.getReport("my-strategy");
+         * console.log(markdown);
+         * ```
+         */
+        this.getReport = async (strategyName) => {
+            backtest$1.loggerService.info(LIVE_METHOD_NAME_GET_REPORT, {
+                strategyName,
+            });
+            return await backtest$1.liveMarkdownService.getReport(strategyName);
+        };
+        /**
+         * Saves strategy report to disk.
+         *
+         * @param strategyName - Strategy name to save report for
+         * @param path - Optional directory path to save report (default: "./logs/live")
+         *
+         * @example
+         * ```typescript
+         * // Save to default path: ./logs/live/my-strategy.md
+         * await Live.dump("my-strategy");
+         *
+         * // Save to custom path: ./custom/path/my-strategy.md
+         * await Live.dump("my-strategy", "./custom/path");
+         * ```
+         */
+        this.dump = async (strategyName, path) => {
+            backtest$1.loggerService.info(LIVE_METHOD_NAME_DUMP, {
+                strategyName,
+                path,
+            });
+            await backtest$1.liveMarkdownService.dump(strategyName, path);
+        };
     }
 }
+/**
+ * Singleton instance of LiveUtils for convenient live trading operations.
+ *
+ * @example
+ * ```typescript
+ * import { Live } from "./classes/Live";
+ *
+ * for await (const result of Live.run("BTCUSDT", {
+ *   strategyName: "my-strategy",
+ *   exchangeName: "my-exchange",
+ * })) {
+ *   console.log("Result:", result.action);
+ * }
+ * ```
+ */
 const Live = new LiveUtils();
 
-export { Backtest, ExecutionContextService, Live, MethodContextService, PersistBase, PersistSignalAdaper, addExchange, addFrame, addStrategy, backtest, formatPrice, formatQuantity, getAveragePrice, getCandles, getDate, getMode, reduce, runBacktest, runBacktestGUI, setLogger, startRun, stopAll, stopRun };
+export { Backtest, ExecutionContextService, Live, MethodContextService, PersistBase, PersistSignalAdaper, addExchange, addFrame, addStrategy, formatPrice, formatQuantity, getAveragePrice, getCandles, getDate, getMode, backtest as lib, listenError, listenSignal, listenSignalBacktest, listenSignalBacktestOnce, listenSignalLive, listenSignalLiveOnce, listenSignalOnce, setLogger };