backtest-kit 1.0.4 → 1.1.0

package/types.d.ts

@@ -22,15 +22,65 @@ interface ILogger {
      * Used to record informational updates, such as successful completions, policy validations, or history commits, providing a high-level overview of system activity without excessive detail.
      */
     info(topic: string, ...args: any[]): void;
+    /**
+     * Logs a warning-level message.
+     * Used to record potentially problematic situations that don't prevent execution but may require attention, such as missing data, unexpected conditions, or deprecated usage.
+     */
+    warn(topic: string, ...args: any[]): void;
 }
 
+/**
+ * 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),
+ * });
+ * ```
+ */
 declare function setLogger(logger: ILogger): Promise<void>;
 
+/**
+ * Execution context containing runtime parameters for strategy/exchange operations.
+ *
+ * Propagated through ExecutionContextService to provide implicit context
+ * for getCandles(), tick(), backtest() and other operations.
+ */
 interface IExecutionContext {
+    /** Trading pair symbol (e.g., "BTCUSDT") */
     symbol: string;
+    /** Current timestamp for operation */
     when: Date;
+    /** Whether running in backtest mode (true) or live mode (false) */
     backtest: boolean;
 }
+/**
+ * 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 }
+ * );
+ * ```
+ */
 declare const ExecutionContextService: (new () => {
     readonly context: IExecutionContext;
 }) & Omit<{
@@ -38,351 +88,2022 @@ declare const ExecutionContextService: (new () => {
         readonly context: IExecutionContext;
     };
 }, "prototype"> & di_scoped.IScopedClassRun<[context: IExecutionContext]>;
+/**
+ * Type helper for ExecutionContextService instance.
+ * Used for dependency injection type annotations.
+ */
 type TExecutionContextService = InstanceType<typeof ExecutionContextService>;
 
+/**
+ * Candle time interval for fetching historical data.
+ */
 type CandleInterval = "1m" | "3m" | "5m" | "15m" | "30m" | "1h" | "2h" | "4h" | "6h" | "8h";
+/**
+ * Single OHLCV candle data point.
+ * Used for VWAP calculation and backtesting.
+ */
 interface ICandleData {
+    /** Unix timestamp in milliseconds when candle opened */
     timestamp: number;
+    /** Opening price at candle start */
     open: number;
+    /** Highest price during candle period */
     high: number;
+    /** Lowest price during candle period */
     low: number;
+    /** Closing price at candle end */
     close: number;
+    /** Trading volume during candle period */
     volume: number;
 }
+/**
+ * Exchange parameters passed to ClientExchange constructor.
+ * Combines schema with runtime dependencies.
+ */
 interface IExchangeParams extends IExchangeSchema {
+    /** Logger service for debug output */
     logger: ILogger;
+    /** Execution context service (symbol, when, backtest flag) */
     execution: TExecutionContextService;
 }
+/**
+ * Optional callbacks for exchange data events.
+ */
 interface IExchangeCallbacks {
+    /** Called when candle data is fetched */
     onCandleData: (symbol: string, interval: CandleInterval, since: Date, limit: number, data: ICandleData[]) => void;
 }
+/**
+ * Exchange schema registered via addExchange().
+ * Defines candle data source and formatting logic.
+ */
 interface IExchangeSchema {
+    /** Unique exchange identifier for registration */
     exchangeName: ExchangeName;
+    /**
+     * Fetch candles from data source (API or database).
+     *
+     * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+     * @param interval - Candle time interval (e.g., "1m", "1h")
+     * @param since - Start date for candle fetching
+     * @param limit - Maximum number of candles to fetch
+     * @returns Promise resolving to array of OHLCV candle data
+     */
     getCandles: (symbol: string, interval: CandleInterval, since: Date, limit: number) => Promise<ICandleData[]>;
+    /**
+     * Format quantity according to exchange precision rules.
+     *
+     * @param symbol - Trading pair symbol
+     * @param quantity - Raw quantity value
+     * @returns Promise resolving to formatted quantity string
+     */
     formatQuantity: (symbol: string, quantity: number) => Promise<string>;
+    /**
+     * Format price according to exchange precision rules.
+     *
+     * @param symbol - Trading pair symbol
+     * @param price - Raw price value
+     * @returns Promise resolving to formatted price string
+     */
     formatPrice: (symbol: string, price: number) => Promise<string>;
+    /** Optional lifecycle event callbacks (onCandleData) */
     callbacks?: Partial<IExchangeCallbacks>;
 }
+/**
+ * Exchange interface implemented by ClientExchange.
+ * Provides candle data access and VWAP calculation.
+ */
 interface IExchange {
+    /**
+     * Fetch historical candles backwards from execution context time.
+     *
+     * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+     * @param interval - Candle time interval (e.g., "1m", "1h")
+     * @param limit - Maximum number of candles to fetch
+     * @returns Promise resolving to array of candle data
+     */
     getCandles: (symbol: string, interval: CandleInterval, limit: number) => Promise<ICandleData[]>;
+    /**
+     * Fetch future candles forward from execution context time (for backtest).
+     *
+     * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+     * @param interval - Candle time interval (e.g., "1m", "1h")
+     * @param limit - Maximum number of candles to fetch
+     * @returns Promise resolving to array of candle data
+     */
     getNextCandles: (symbol: string, interval: CandleInterval, limit: number) => Promise<ICandleData[]>;
+    /**
+     * Format quantity for exchange precision.
+     *
+     * @param symbol - Trading pair symbol
+     * @param quantity - Raw quantity value
+     * @returns Promise resolving to formatted quantity string
+     */
     formatQuantity: (symbol: string, quantity: number) => Promise<string>;
+    /**
+     * Format price for exchange precision.
+     *
+     * @param symbol - Trading pair symbol
+     * @param price - Raw price value
+     * @returns Promise resolving to formatted price string
+     */
     formatPrice: (symbol: string, price: number) => Promise<string>;
+    /**
+     * Calculate VWAP from last 5 1-minute candles.
+     *
+     * Formula: VWAP = Σ(Typical Price × Volume) / Σ(Volume)
+     * where Typical Price = (High + Low + Close) / 3
+     *
+     * @param symbol - Trading pair symbol
+     * @returns Promise resolving to volume-weighted average price
+     */
     getAveragePrice: (symbol: string) => Promise<number>;
 }
+/**
+ * Unique exchange identifier.
+ */
 type ExchangeName = string;
 
+/**
+ * Timeframe interval for backtest period generation.
+ * Determines the granularity of timestamps in the generated timeframe array.
+ *
+ * Minutes: 1m, 3m, 5m, 15m, 30m
+ * Hours: 1h, 2h, 4h, 6h, 8h, 12h
+ * Days: 1d, 3d
+ */
+type FrameInterval = "1m" | "3m" | "5m" | "15m" | "30m" | "1h" | "2h" | "4h" | "6h" | "8h" | "12h" | "1d" | "3d";
+/**
+ * Frame parameters passed to ClientFrame constructor.
+ * Extends IFrameSchema with logger instance for internal logging.
+ */
+interface IFrameParams extends IFrameSchema {
+    /** Logger service for debug output */
+    logger: ILogger;
+}
+/**
+ * Callbacks for frame lifecycle events.
+ */
+interface IFrameCallbacks {
+    /**
+     * Called after timeframe array generation.
+     * Useful for logging or validating the generated timeframes.
+     *
+     * @param timeframe - Array of Date objects representing tick timestamps
+     * @param startDate - Start of the backtest period
+     * @param endDate - End of the backtest period
+     * @param interval - Interval used for generation
+     */
+    onTimeframe: (timeframe: Date[], startDate: Date, endDate: Date, interval: FrameInterval) => void;
+}
+/**
+ * Frame schema registered via addFrame().
+ * Defines backtest period and interval for timestamp generation.
+ *
+ * @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} timestamps`);
+ *     },
+ *   },
+ * });
+ * ```
+ */
+interface IFrameSchema {
+    /** Unique identifier for this frame */
+    frameName: FrameName;
+    /** Interval for timestamp generation */
+    interval: FrameInterval;
+    /** Start of backtest period (inclusive) */
+    startDate: Date;
+    /** End of backtest period (inclusive) */
+    endDate: Date;
+    /** Optional lifecycle callbacks */
+    callbacks?: Partial<IFrameCallbacks>;
+}
+/**
+ * Frame interface for timeframe generation.
+ * Used internally by backtest orchestration.
+ */
+interface IFrame {
+    /**
+     * Generates array of timestamps for backtest iteration.
+     * Timestamps are spaced according to the configured interval.
+     *
+     * @param symbol - Trading pair symbol (unused, for API consistency)
+     * @returns Promise resolving to array of Date objects
+     */
+    getTimeframe: (symbol: string) => Promise<Date[]>;
+}
+/**
+ * Unique identifier for a frame schema.
+ * Used to retrieve frame instances via dependency injection.
+ */
+type FrameName = string;
+
+/**
+ * Method context containing schema names for operation routing.
+ *
+ * Propagated through MethodContextService to provide implicit context
+ * for retrieving correct strategy/exchange/frame instances.
+ */
+interface IMethodContext {
+    /** Name of exchange schema to use */
+    exchangeName: ExchangeName;
+    /** Name of strategy schema to use */
+    strategyName: StrategyName;
+    /** Name of frame schema to use (empty string for live mode) */
+    frameName: FrameName;
+}
+/**
+ * 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"
+ *   }
+ * );
+ * ```
+ */
+declare const MethodContextService: (new () => {
+    readonly context: IMethodContext;
+}) & Omit<{
+    new (context: IMethodContext): {
+        readonly context: IMethodContext;
+    };
+}, "prototype"> & di_scoped.IScopedClassRun<[context: IMethodContext]>;
+
+/**
+ * Signal generation interval for throttling.
+ * Enforces minimum time between getSignal calls.
+ */
 type SignalInterval = "1m" | "3m" | "5m" | "15m" | "30m" | "1h";
+/**
+ * Signal data transfer object returned by getSignal.
+ * Will be validated and augmented with auto-generated id.
+ */
 interface ISignalDto {
+    /** Optional signal ID (auto-generated if not provided) */
     id?: string;
+    /** Trade direction: "long" (buy) or "short" (sell) */
     position: "long" | "short";
-    note: string;
+    /** Human-readable description of signal reason */
+    note?: string;
+    /** Entry price for the position */
     priceOpen: number;
+    /** Take profit target price (must be > priceOpen for long, < priceOpen for short) */
     priceTakeProfit: number;
+    /** Stop loss exit price (must be < priceOpen for long, > priceOpen for short) */
     priceStopLoss: number;
+    /** Expected duration in minutes before time_expired */
     minuteEstimatedTime: number;
-    timestamp: number;
 }
+/**
+ * Complete signal with auto-generated id.
+ * Used throughout the system after validation.
+ */
 interface ISignalRow extends ISignalDto {
+    /** Unique signal identifier (UUID v4 auto-generated) */
     id: string;
+    /** Unique exchange identifier for execution */
+    exchangeName: ExchangeName;
+    /** Unique strategy identifier for execution */
+    strategyName: StrategyName;
+    /** Signal creation timestamp in milliseconds */
+    timestamp: number;
+    /** Trading pair symbol (e.g., "BTCUSDT") */
+    symbol: string;
 }
+/**
+ * Optional lifecycle callbacks for signal events.
+ * Called when signals are opened, active, idle, or closed.
+ */
 interface IStrategyCallbacks {
-    onOpen: (backtest: boolean, symbol: string, data: ISignalRow) => void;
-    onClose: (backtest: boolean, symbol: string, priceClose: number, data: ISignalRow) => void;
+    /** Called on every tick with the result */
+    onTick: (symbol: string, result: IStrategyTickResult, backtest: boolean) => void;
+    /** Called when new signal is opened (after validation) */
+    onOpen: (symbol: string, data: ISignalRow, currentPrice: number, backtest: boolean) => void;
+    /** Called when signal is being monitored (active state) */
+    onActive: (symbol: string, data: ISignalRow, currentPrice: number, backtest: boolean) => void;
+    /** Called when no active signal exists (idle state) */
+    onIdle: (symbol: string, currentPrice: number, backtest: boolean) => void;
+    /** Called when signal is closed with final price */
+    onClose: (symbol: string, data: ISignalRow, priceClose: number, backtest: boolean) => void;
 }
+/**
+ * Strategy schema registered via addStrategy().
+ * Defines signal generation logic and configuration.
+ */
 interface IStrategySchema {
+    /** Unique strategy identifier for registration */
     strategyName: StrategyName;
+    /** Minimum interval between getSignal calls (throttling) */
     interval: SignalInterval;
+    /** Signal generation function (returns null if no signal, validated DTO if signal) */
     getSignal: (symbol: string) => Promise<ISignalDto | null>;
+    /** Optional lifecycle event callbacks (onOpen, onClose) */
     callbacks?: Partial<IStrategyCallbacks>;
 }
+/**
+ * Reason why signal was closed.
+ * Used in discriminated union for type-safe handling.
+ */
 type StrategyCloseReason = "time_expired" | "take_profit" | "stop_loss";
+/**
+ * Profit and loss calculation result.
+ * Includes adjusted prices with fees (0.1%) and slippage (0.1%).
+ */
 interface IStrategyPnL {
+    /** Profit/loss as percentage (e.g., 1.5 for +1.5%, -2.3 for -2.3%) */
     pnlPercentage: number;
+    /** Entry price adjusted with slippage and fees */
     priceOpen: number;
+    /** Exit price adjusted with slippage and fees */
     priceClose: number;
 }
+/**
+ * Tick result: no active signal, idle state.
+ */
 interface IStrategyTickResultIdle {
+    /** Discriminator for type-safe union */
     action: "idle";
+    /** No signal in idle state */
     signal: null;
+    /** Strategy name for tracking idle events */
+    strategyName: StrategyName;
+    /** Exchange name for tracking idle events */
+    exchangeName: ExchangeName;
+    /** Current VWAP price during idle state */
+    currentPrice: number;
 }
+/**
+ * Tick result: new signal just created.
+ * Triggered after getSignal validation and persistence.
+ */
 interface IStrategyTickResultOpened {
+    /** Discriminator for type-safe union */
     action: "opened";
+    /** Newly created and validated signal with generated ID */
     signal: ISignalRow;
+    /** Strategy name for tracking */
+    strategyName: StrategyName;
+    /** Exchange name for tracking */
+    exchangeName: ExchangeName;
+    /** Current VWAP price at signal open */
+    currentPrice: number;
 }
+/**
+ * Tick result: signal is being monitored.
+ * Waiting for TP/SL or time expiration.
+ */
 interface IStrategyTickResultActive {
+    /** Discriminator for type-safe union */
     action: "active";
+    /** Currently monitored signal */
     signal: ISignalRow;
+    /** Current VWAP price for monitoring */
     currentPrice: number;
+    /** Strategy name for tracking */
+    strategyName: StrategyName;
+    /** Exchange name for tracking */
+    exchangeName: ExchangeName;
 }
+/**
+ * Tick result: signal closed with PNL.
+ * Final state with close reason and profit/loss calculation.
+ */
 interface IStrategyTickResultClosed {
+    /** Discriminator for type-safe union */
     action: "closed";
+    /** Completed signal with original parameters */
     signal: ISignalRow;
+    /** Final VWAP price at close */
     currentPrice: number;
+    /** Why signal closed (time_expired | take_profit | stop_loss) */
     closeReason: StrategyCloseReason;
+    /** Unix timestamp in milliseconds when signal closed */
     closeTimestamp: number;
+    /** Profit/loss calculation with fees and slippage */
     pnl: IStrategyPnL;
+    /** Strategy name for tracking */
+    strategyName: StrategyName;
+    /** Exchange name for tracking */
+    exchangeName: ExchangeName;
 }
+/**
+ * Discriminated union of all tick results.
+ * Use type guards: `result.action === "closed"` for type safety.
+ */
 type IStrategyTickResult = IStrategyTickResultIdle | IStrategyTickResultOpened | IStrategyTickResultActive | IStrategyTickResultClosed;
+/**
+ * Backtest always returns closed result (TP/SL or time_expired).
+ */
 type IStrategyBacktestResult = IStrategyTickResultClosed;
+/**
+ * Strategy interface implemented by ClientStrategy.
+ * Defines core strategy execution methods.
+ */
 interface IStrategy {
+    /**
+     * Single tick of strategy execution with VWAP monitoring.
+     * Checks for signal generation (throttled) and TP/SL conditions.
+     *
+     * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+     * @returns Promise resolving to tick result (idle | opened | active | closed)
+     */
     tick: (symbol: string) => Promise<IStrategyTickResult>;
+    /**
+     * Fast backtest using historical candles.
+     * Iterates through candles, calculates VWAP, checks TP/SL on each candle.
+     *
+     * @param candles - Array of historical candle data
+     * @returns Promise resolving to closed result (always completes signal)
+     */
     backtest: (candles: ICandleData[]) => Promise<IStrategyBacktestResult>;
 }
+/**
+ * Unique strategy identifier.
+ */
 type StrategyName = string;
 
-type FrameInterval = "1m" | "3m" | "5m" | "15m" | "30m" | "1h" | "2h" | "4h" | "6h" | "8h" | "12h" | "1d" | "3d";
-interface IFrameParams extends IFrameSchema {
-    logger: ILogger;
-}
-interface IFrameCallbacks {
-    onTimeframe: (timeframe: Date[], startDate: Date, endDate: Date, interval: FrameInterval) => void;
-}
-interface IFrameSchema {
-    frameName: FrameName;
-    interval: FrameInterval;
-    startDate: Date;
-    endDate: Date;
-    callbacks?: Partial<IFrameCallbacks>;
-}
-interface IFrame {
-    getTimeframe: (symbol: string) => Promise<Date[]>;
-}
-type FrameName = string;
-
+/**
+ * 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"),
+ *   },
+ * });
+ * ```
+ */
 declare function addStrategy(strategySchema: IStrategySchema): void;
+/**
+ * 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),
+ * });
+ * ```
+ */
 declare function addExchange(exchangeSchema: IExchangeSchema): void;
+/**
+ * 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`);
+ *     },
+ *   },
+ * });
+ * ```
+ */
 declare function addFrame(frameSchema: IFrameSchema): void;
 
-interface IBacktestResult {
-    symbol: string;
-    results: IStrategyTickResult[];
-}
-declare function runBacktest(symbol: string, timeframes: Date[]): Promise<IBacktestResult>;
-declare function runBacktestGUI(symbol: string, timeframes: Date[]): Promise<void>;
-
-interface IReduceResult<T> {
-    symbol: string;
-    accumulator: T;
-    totalTicks: number;
-}
-type ReduceCallback<T> = (accumulator: T, index: number, when: Date, symbol: string) => T | Promise<T>;
-declare function reduce<T>(symbol: string, timeframes: Date[], callback: ReduceCallback<T>, initialValue: T): Promise<IReduceResult<T>>;
-
-interface IRunConfig {
-    symbol: string;
-    interval: number;
-}
-declare function startRun(config: IRunConfig): void;
-declare function stopRun(symbol: string): void;
-declare function stopAll(): void;
+/**
+ * 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();
+ * ```
+ */
+declare function listenSignal(fn: (event: IStrategyTickResult) => void): () => void;
+/**
+ * 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();
+ * ```
+ */
+declare function listenSignalOnce(filterFn: (event: IStrategyTickResult) => boolean, fn: (event: IStrategyTickResult) => void): () => void;
+/**
+ * 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);
+ *   }
+ * });
+ * ```
+ */
+declare function listenSignalLive(fn: (event: IStrategyTickResult) => void): () => void;
+/**
+ * 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)
+ * );
+ * ```
+ */
+declare function listenSignalLiveOnce(filterFn: (event: IStrategyTickResult) => boolean, fn: (event: IStrategyTickResult) => void): () => void;
+/**
+ * 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);
+ *   }
+ * });
+ * ```
+ */
+declare function listenSignalBacktest(fn: (event: IStrategyTickResult) => void): () => void;
+/**
+ * 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)
+ * );
+ * ```
+ */
+declare function listenSignalBacktestOnce(filterFn: (event: IStrategyTickResult) => boolean, fn: (event: IStrategyTickResult) => void): () => void;
+/**
+ * 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();
+ * ```
+ */
+declare function listenError(fn: (error: Error) => void): () => void;
 
+/**
+ * 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 }
+ * ```
+ */
 declare function getCandles(symbol: string, interval: CandleInterval, limit: number): Promise<ICandleData[]>;
+/**
+ * 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
+ * ```
+ */
 declare function getAveragePrice(symbol: string): Promise<number>;
+/**
+ * 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"
+ * ```
+ */
 declare function formatPrice(symbol: string, price: number): Promise<string>;
+/**
+ * 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"
+ * ```
+ */
 declare function formatQuantity(symbol: string, quantity: number): Promise<string>;
+/**
+ * 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
+ * ```
+ */
 declare function getDate(): Promise<Date>;
+/**
+ * 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");
+ * }
+ * ```
+ */
 declare function getMode(): Promise<"backtest" | "live">;
 
-interface IMethodContext {
-    exchangeName: ExchangeName;
-    strategyName: StrategyName;
-    frameName: FrameName;
-}
-declare const MethodContextService: (new () => {
-    readonly context: IMethodContext;
-}) & Omit<{
-    new (context: IMethodContext): {
-        readonly context: IMethodContext;
-    };
-}, "prototype"> & di_scoped.IScopedClassRun<[context: IMethodContext]>;
-
 declare const BASE_WAIT_FOR_INIT_SYMBOL: unique symbol;
+/**
+ * Signal data stored in persistence layer.
+ * Contains nullable signal for atomic updates.
+ */
 interface ISignalData {
+    /** Current signal state (null when no active signal) */
     signalRow: ISignalRow | null;
 }
+/**
+ * Type helper for PersistBase instance.
+ */
 type TPersistBase = InstanceType<typeof PersistBase>;
+/**
+ * Constructor type for PersistBase.
+ * Used for custom persistence adapters.
+ */
 type TPersistBaseCtor<EntityName extends string = string, Entity extends IEntity = IEntity> = new (entityName: EntityName, baseDir: string) => IPersistBase<Entity>;
+/**
+ * Entity identifier - string or number.
+ */
 type EntityId = string | number;
+/**
+ * Base interface for persisted entities.
+ */
 interface IEntity {
 }
+/**
+ * Persistence interface for CRUD operations.
+ * Implemented by PersistBase.
+ */
 interface IPersistBase<Entity extends IEntity = IEntity> {
+    /**
+     * Initialize persistence directory and validate existing files.
+     * Uses singleshot to ensure one-time execution.
+     *
+     * @param initial - Whether this is the first initialization
+     * @returns Promise that resolves when initialization is complete
+     */
     waitForInit(initial: boolean): Promise<void>;
+    /**
+     * Read entity from persistence storage.
+     *
+     * @param entityId - Unique entity identifier
+     * @returns Promise resolving to entity data
+     * @throws Error if entity not found or read fails
+     */
     readValue(entityId: EntityId): Promise<Entity>;
+    /**
+     * Check if entity exists in storage.
+     *
+     * @param entityId - Unique entity identifier
+     * @returns Promise resolving to true if exists, false otherwise
+     */
     hasValue(entityId: EntityId): Promise<boolean>;
+    /**
+     * Write entity to storage with atomic file writes.
+     *
+     * @param entityId - Unique entity identifier
+     * @param entity - Entity data to persist
+     * @returns Promise that resolves when write is complete
+     * @throws Error if write fails
+     */
     writeValue(entityId: EntityId, entity: Entity): Promise<void>;
 }
+/**
+ * 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");
+ * ```
+ */
 declare const PersistBase: {
     new <EntityName extends string = string>(entityName: EntityName, baseDir?: string): {
+        /** Computed directory path for entity storage */
         _directory: string;
         readonly entityName: EntityName;
         readonly baseDir: string;
+        /**
+         * Computes file path for entity ID.
+         *
+         * @param entityId - Entity identifier
+         * @returns Full file path to entity JSON file
+         */
         _getFilePath(entityId: EntityId): string;
         waitForInit(initial: boolean): Promise<void>;
+        /**
+         * Returns count of persisted entities.
+         *
+         * @returns Promise resolving to number of .json files in directory
+         */
         getCount(): Promise<number>;
         readValue<T extends IEntity = IEntity>(entityId: EntityId): Promise<T>;
         hasValue(entityId: EntityId): Promise<boolean>;
         writeValue<T extends IEntity = IEntity>(entityId: EntityId, entity: T): Promise<void>;
+        /**
+         * 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
+         */
         removeValue(entityId: EntityId): Promise<void>;
+        /**
+         * Removes all entities from storage.
+         *
+         * @returns Promise that resolves when all entities are deleted
+         * @throws Error if deletion fails
+         */
         removeAll(): Promise<void>;
+        /**
+         * Async generator yielding all entity values.
+         * Sorted alphanumerically by entity ID.
+         *
+         * @returns AsyncGenerator yielding entities
+         * @throws Error if reading fails
+         */
         values<T extends IEntity = IEntity>(): AsyncGenerator<T>;
+        /**
+         * Async generator yielding all entity IDs.
+         * Sorted alphanumerically.
+         *
+         * @returns AsyncGenerator yielding entity IDs
+         * @throws Error if reading fails
+         */
         keys(): AsyncGenerator<EntityId>;
+        /**
+         * Filters entities by predicate function.
+         *
+         * @param predicate - Filter function
+         * @returns AsyncGenerator yielding filtered entities
+         */
         filter<T extends IEntity = IEntity>(predicate: (value: T) => boolean): AsyncGenerator<T>;
+        /**
+         * 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
+         */
         take<T extends IEntity = IEntity>(total: number, predicate?: (value: T) => boolean): AsyncGenerator<T>;
         [BASE_WAIT_FOR_INIT_SYMBOL]: (() => Promise<void>) & functools_kit.ISingleshotClearable;
+        /**
+         * Async iterator implementation.
+         * Delegates to values() generator.
+         *
+         * @returns AsyncIterableIterator yielding entities
+         */
         [Symbol.asyncIterator](): AsyncIterableIterator<any>;
     };
 };
+/**
+ * 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.
+ */
 declare class PersistSignalUtils {
     private PersistSignalFactory;
     private getSignalStorage;
+    /**
+     * 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: TPersistBaseCtor<StrategyName, ISignalData>): void;
+    /**
+     * 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
+     */
     readSignalData: (strategyName: StrategyName, symbol: string) => Promise<ISignalRow | 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
+     */
     writeSignalData: (signalRow: ISignalRow | null, strategyName: StrategyName, symbol: string) => Promise<void>;
 }
+/**
+ * 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");
+ * ```
+ */
 declare const PersistSignalAdaper: PersistSignalUtils;
 
+/**
+ * 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);
+ * }
+ * ```
+ */
 declare class BacktestUtils {
+    /**
+     * 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
+     */
     run: (symbol: string, context: {
         strategyName: string;
         exchangeName: string;
         frameName: string;
     }) => AsyncGenerator<IStrategyTickResultClosed, void, unknown>;
+    /**
+     * 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");
+     * ```
+     */
+    background: (symbol: string, context: {
+        strategyName: string;
+        exchangeName: string;
+        frameName: string;
+    }) => Promise<() => void>;
+    /**
+     * 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);
+     * ```
+     */
+    getReport: (strategyName: StrategyName) => Promise<string>;
+    /**
+     * 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");
+     * ```
+     */
+    dump: (strategyName: StrategyName, path?: string) => Promise<void>;
 }
+/**
+ * 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);
+ *   }
+ * }
+ * ```
+ */
 declare const Backtest: BacktestUtils;
 
+/**
+ * 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);
+ *   }
+ * }
+ * ```
+ */
 declare class LiveUtils {
+    /**
+     * 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
+     */
     run: (symbol: string, context: {
         strategyName: string;
         exchangeName: string;
-        frameName: string;
     }) => AsyncGenerator<IStrategyTickResultOpened | IStrategyTickResultClosed, void, unknown>;
+    /**
+     * 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"
+     * });
+     * ```
+     */
+    background: (symbol: string, context: {
+        strategyName: string;
+        exchangeName: string;
+    }) => Promise<() => void>;
+    /**
+     * 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);
+     * ```
+     */
+    getReport: (strategyName: StrategyName) => Promise<string>;
+    /**
+     * 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");
+     * ```
+     */
+    dump: (strategyName: StrategyName, path?: string) => Promise<void>;
 }
+/**
+ * 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);
+ * }
+ * ```
+ */
 declare const Live: LiveUtils;
 
+/**
+ * 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.
+ */
 declare class LoggerService implements ILogger {
     private readonly methodContextService;
     private readonly executionContextService;
     private _commonLogger;
+    /**
+     * Gets current method context if available.
+     * Contains strategyName, exchangeName, frameName from MethodContextService.
+     */
     private get methodContext();
+    /**
+     * Gets current execution context if available.
+     * Contains symbol, when, backtest from ExecutionContextService.
+     */
     private get executionContext();
+    /**
+     * Logs general-purpose message with automatic context injection.
+     *
+     * @param topic - Log topic/category
+     * @param args - Additional log arguments
+     */
     log: (topic: string, ...args: any[]) => Promise<void>;
+    /**
+     * Logs debug-level message with automatic context injection.
+     *
+     * @param topic - Log topic/category
+     * @param args - Additional log arguments
+     */
     debug: (topic: string, ...args: any[]) => Promise<void>;
+    /**
+     * Logs info-level message with automatic context injection.
+     *
+     * @param topic - Log topic/category
+     * @param args - Additional log arguments
+     */
     info: (topic: string, ...args: any[]) => Promise<void>;
+    /**
+     * Logs warning-level message with automatic context injection.
+     *
+     * @param topic - Log topic/category
+     * @param args - Additional log arguments
+     */
+    warn: (topic: string, ...args: any[]) => Promise<void>;
+    /**
+     * Sets custom logger implementation.
+     *
+     * @param logger - Custom logger implementing ILogger interface
+     */
     setLogger: (logger: ILogger) => void;
 }
 
+/**
+ * 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");
+ * ```
+ */
 declare class ClientExchange implements IExchange {
     readonly params: IExchangeParams;
     constructor(params: IExchangeParams);
+    /**
+     * 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
+     */
     getCandles(symbol: string, interval: CandleInterval, limit: number): Promise<ICandleData[]>;
+    /**
+     * 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
+     */
     getNextCandles(symbol: string, interval: CandleInterval, limit: number): Promise<ICandleData[]>;
+    /**
+     * 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
+     */
     getAveragePrice(symbol: string): Promise<number>;
     formatQuantity(symbol: string, quantity: number): Promise<string>;
     formatPrice(symbol: string, price: number): Promise<string>;
 }
 
+/**
+ * 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
+ * ```
+ */
 declare class ExchangeConnectionService implements IExchange {
     private readonly loggerService;
     private readonly executionContextService;
     private readonly exchangeSchemaService;
     private readonly methodContextService;
+    /**
+     * 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
+     */
     getExchange: ((exchangeName: ExchangeName) => ClientExchange) & functools_kit.IClearableMemoize<string> & functools_kit.IControlMemoize<string, ClientExchange>;
+    /**
+     * 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
+     */
     getCandles: (symbol: string, interval: CandleInterval, limit: number) => Promise<ICandleData[]>;
+    /**
+     * 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
+     */
     getNextCandles: (symbol: string, interval: CandleInterval, limit: number) => Promise<ICandleData[]>;
+    /**
+     * 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
+     */
     getAveragePrice: (symbol: string) => Promise<number>;
+    /**
+     * 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
+     */
     formatPrice: (symbol: string, price: number) => Promise<string>;
+    /**
+     * 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
+     */
     formatQuantity: (symbol: string, quantity: number) => Promise<string>;
 }
 
+/**
+ * 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
+ * ```
+ */
 declare class StrategyConnectionService implements IStrategy {
     private readonly loggerService;
     private readonly executionContextService;
     private readonly strategySchemaService;
     private readonly exchangeConnectionService;
     private readonly methodContextService;
+    /**
+     * 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
+     */
     private getStrategy;
+    /**
+     * 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)
+     */
     tick: () => Promise<IStrategyTickResult>;
+    /**
+     * 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)
+     */
     backtest: (candles: ICandleData[]) => Promise<IStrategyBacktestResult>;
 }
 
+/**
+ * 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.
+ */
 declare class ClientFrame implements IFrame {
     readonly params: IFrameParams;
     constructor(params: IFrameParams);
+    /**
+     * 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
+     */
     getTimeframe: ((symbol: string) => Promise<Date[]>) & functools_kit.ISingleshotClearable;
 }
 
+/**
+ * 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
+ * ```
+ */
 declare class FrameConnectionService implements IFrame {
     private readonly loggerService;
     private readonly frameSchemaService;
     private readonly methodContextService;
+    /**
+     * 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
+     */
     getFrame: ((frameName: FrameName) => ClientFrame) & functools_kit.IClearableMemoize<string> & functools_kit.IControlMemoize<string, ClientFrame>;
+    /**
+     * 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 }
+     */
     getTimeframe: (symbol: string) => Promise<Date[]>;
 }
 
+/**
+ * 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.
+ */
 declare class ExchangeGlobalService {
     private readonly loggerService;
     private readonly 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
+     */
     getCandles: (symbol: string, interval: CandleInterval, limit: number, when: Date, backtest: boolean) => Promise<ICandleData[]>;
+    /**
+     * 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
+     */
     getNextCandles: (symbol: string, interval: CandleInterval, limit: number, when: Date, backtest: boolean) => Promise<ICandleData[]>;
+    /**
+     * 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
+     */
     getAveragePrice: (symbol: string, when: Date, backtest: boolean) => Promise<number>;
+    /**
+     * 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
+     */
     formatPrice: (symbol: string, price: number, when: Date, backtest: boolean) => Promise<string>;
+    /**
+     * 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
+     */
     formatQuantity: (symbol: string, quantity: number, when: Date, backtest: boolean) => Promise<string>;
 }
 
+/**
+ * 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.
+ */
 declare class StrategyGlobalService {
     private readonly loggerService;
     private readonly 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)
+     */
     tick: (symbol: string, when: Date, backtest: boolean) => Promise<IStrategyTickResult>;
+    /**
+     * 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
+     */
     backtest: (symbol: string, candles: ICandleData[], when: Date, backtest: boolean) => Promise<IStrategyBacktestResult>;
 }
 
+/**
+ * Global service for frame operations.
+ *
+ * Wraps FrameConnectionService for timeframe generation.
+ * Used internally by BacktestLogicPrivateService.
+ */
 declare class FrameGlobalService {
     private readonly loggerService;
     private readonly frameConnectionService;
+    /**
+     * Generates timeframe array for backtest iteration.
+     *
+     * @param symbol - Trading pair symbol
+     * @returns Promise resolving to array of Date objects
+     */
     getTimeframe: (symbol: string) => Promise<Date[]>;
 }
 
+/**
+ * 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.
+ */
 declare class ExchangeSchemaService {
     readonly loggerService: LoggerService;
     private _registry;
+    /**
+     * Registers a new exchange schema.
+     *
+     * @param key - Unique exchange name
+     * @param value - Exchange schema configuration
+     * @throws Error if exchange name already exists
+     */
     register: (key: ExchangeName, value: IExchangeSchema) => void;
+    /**
+     * 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
+     */
+    private validateShallow;
+    /**
+     * 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
+     */
     override: (key: ExchangeName, value: Partial<IExchangeSchema>) => IExchangeSchema;
+    /**
+     * Retrieves an exchange schema by name.
+     *
+     * @param key - Exchange name
+     * @returns Exchange schema configuration
+     * @throws Error if exchange name doesn't exist
+     */
     get: (key: ExchangeName) => IExchangeSchema;
 }
 
+/**
+ * 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.
+ */
 declare class StrategySchemaService {
     readonly loggerService: LoggerService;
     private _registry;
+    /**
+     * Registers a new strategy schema.
+     *
+     * @param key - Unique strategy name
+     * @param value - Strategy schema configuration
+     * @throws Error if strategy name already exists
+     */
     register: (key: StrategyName, value: IStrategySchema) => void;
+    /**
+     * 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
+     */
+    private validateShallow;
+    /**
+     * 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
+     */
     override: (key: StrategyName, value: Partial<IStrategySchema>) => IStrategySchema;
+    /**
+     * Retrieves a strategy schema by name.
+     *
+     * @param key - Strategy name
+     * @returns Strategy schema configuration
+     * @throws Error if strategy name doesn't exist
+     */
     get: (key: StrategyName) => IStrategySchema;
 }
 
+/**
+ * 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.
+ */
 declare class FrameSchemaService {
+    readonly loggerService: LoggerService;
     private _registry;
+    /**
+     * Registers a new frame schema.
+     *
+     * @param key - Unique frame name
+     * @param value - Frame schema configuration
+     * @throws Error if frame name already exists
+     */
     register(key: FrameName, value: IFrameSchema): void;
+    /**
+     * 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
+     */
+    private validateShallow;
+    /**
+     * 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: FrameName, value: Partial<IFrameSchema>): void;
+    /**
+     * Retrieves a frame schema by name.
+     *
+     * @param key - Frame name
+     * @returns Frame schema configuration
+     * @throws Error if frame name doesn't exist
+     */
     get(key: FrameName): IFrameSchema;
 }
 
+/**
+ * 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.
+ */
 declare class BacktestLogicPrivateService {
     private readonly loggerService;
     private readonly strategyGlobalService;
     private readonly exchangeGlobalService;
     private readonly 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
+     * }
+     * ```
+     */
     run(symbol: string): AsyncGenerator<IStrategyTickResultClosed, void, unknown>;
 }
 
+/**
+ * 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)
+ */
 declare class LiveLogicPrivateService {
     private readonly loggerService;
     private readonly 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
+     * }
+     * ```
+     */
     run(symbol: string): AsyncGenerator<IStrategyTickResultOpened | IStrategyTickResultClosed, void, unknown>;
 }
 
+/**
+ * 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);
+ *   }
+ * }
+ * ```
+ */
 declare class BacktestLogicPublicService {
     private readonly loggerService;
     private readonly 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
+     */
     run: (symbol: string, context: {
         strategyName: string;
         exchangeName: string;
@@ -390,27 +2111,102 @@ declare class BacktestLogicPublicService {
     }) => AsyncGenerator<IStrategyTickResultClosed, void, unknown>;
 }
 
+/**
+ * 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);
+ *   }
+ * }
+ * ```
+ */
 declare class LiveLogicPublicService {
     private readonly loggerService;
     private readonly 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
+     */
     run: (symbol: string, context: {
         strategyName: string;
         exchangeName: string;
     }) => AsyncGenerator<IStrategyTickResultOpened | IStrategyTickResultClosed, void, unknown>;
 }
 
+/**
+ * Global service providing access to live trading functionality.
+ *
+ * Simple wrapper around LiveLogicPublicService for dependency injection.
+ * Used by public API exports.
+ */
 declare class LiveGlobalService {
     private readonly loggerService;
     private readonly liveLogicPublicService;
+    private readonly strategyValidationService;
+    private readonly 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
+     */
     run: (symbol: string, context: {
         strategyName: string;
         exchangeName: string;
     }) => AsyncGenerator<IStrategyTickResultOpened | IStrategyTickResultClosed, void, unknown>;
 }
 
+/**
+ * Global service providing access to backtest functionality.
+ *
+ * Simple wrapper around BacktestLogicPublicService for dependency injection.
+ * Used by public API exports.
+ */
 declare class BacktestGlobalService {
     private readonly loggerService;
     private readonly backtestLogicPublicService;
+    private readonly strategyValidationService;
+    private readonly exchangeValidationService;
+    private readonly 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
+     */
     run: (symbol: string, context: {
         strategyName: string;
         exchangeName: string;
@@ -418,7 +2214,356 @@ declare class BacktestGlobalService {
     }) => AsyncGenerator<IStrategyTickResultClosed, void, unknown>;
 }
 
+/**
+ * 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");
+ * ```
+ */
+declare class BacktestMarkdownService {
+    /** Logger service for debug output */
+    private readonly loggerService;
+    /**
+     * Memoized function to get or create ReportStorage for a strategy.
+     * Each strategy gets its own isolated storage instance.
+     */
+    private getStorage;
+    /**
+     * 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);
+     *   }
+     * }
+     * ```
+     */
+    private tick;
+    /**
+     * 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);
+     * ```
+     */
+    getReport: (strategyName: StrategyName) => Promise<string>;
+    /**
+     * 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");
+     * ```
+     */
+    dump: (strategyName: StrategyName, path?: string) => Promise<void>;
+    /**
+     * 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();
+     * ```
+     */
+    clear: (strategyName?: StrategyName) => Promise<void>;
+    /**
+     * 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
+     * ```
+     */
+    protected init: (() => Promise<void>) & functools_kit.ISingleshotClearable;
+}
+
+/**
+ * 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");
+ * ```
+ */
+declare class LiveMarkdownService {
+    /** Logger service for debug output */
+    private readonly loggerService;
+    /**
+     * Memoized function to get or create ReportStorage for a strategy.
+     * Each strategy gets its own isolated storage instance.
+     */
+    private getStorage;
+    /**
+     * 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);
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    private tick;
+    /**
+     * 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);
+     * ```
+     */
+    getReport: (strategyName: StrategyName) => Promise<string>;
+    /**
+     * 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");
+     * ```
+     */
+    dump: (strategyName: StrategyName, path?: string) => Promise<void>;
+    /**
+     * 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();
+     * ```
+     */
+    clear: (strategyName?: StrategyName) => Promise<void>;
+    /**
+     * 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
+     * ```
+     */
+    protected init: (() => Promise<void>) & functools_kit.ISingleshotClearable;
+}
+
+/**
+ * @class ExchangeValidationService
+ * Service for managing and validating exchange configurations
+ */
+declare class ExchangeValidationService {
+    /**
+     * @private
+     * @readonly
+     * Injected logger service instance
+     */
+    private readonly loggerService;
+    /**
+     * @private
+     * Map storing exchange schemas by exchange name
+     */
+    private _exchangeMap;
+    /**
+     * Adds an exchange schema to the validation service
+     * @public
+     * @throws {Error} If exchangeName already exists
+     */
+    addExchange: (exchangeName: ExchangeName, exchangeSchema: IExchangeSchema) => void;
+    /**
+     * Validates the existence of an exchange
+     * @public
+     * @throws {Error} If exchangeName is not found
+     * Memoized function to cache validation results
+     */
+    validate: (exchangeName: ExchangeName, source: string) => void;
+}
+
+/**
+ * @class StrategyValidationService
+ * Service for managing and validating strategy configurations
+ */
+declare class StrategyValidationService {
+    /**
+     * @private
+     * @readonly
+     * Injected logger service instance
+     */
+    private readonly loggerService;
+    /**
+     * @private
+     * Map storing strategy schemas by strategy name
+     */
+    private _strategyMap;
+    /**
+     * Adds a strategy schema to the validation service
+     * @public
+     * @throws {Error} If strategyName already exists
+     */
+    addStrategy: (strategyName: StrategyName, strategySchema: IStrategySchema) => void;
+    /**
+     * Validates the existence of a strategy
+     * @public
+     * @throws {Error} If strategyName is not found
+     * Memoized function to cache validation results
+     */
+    validate: (strategyName: StrategyName, source: string) => void;
+}
+
+/**
+ * @class FrameValidationService
+ * Service for managing and validating frame configurations
+ */
+declare class FrameValidationService {
+    /**
+     * @private
+     * @readonly
+     * Injected logger service instance
+     */
+    private readonly loggerService;
+    /**
+     * @private
+     * Map storing frame schemas by frame name
+     */
+    private _frameMap;
+    /**
+     * Adds a frame schema to the validation service
+     * @public
+     * @throws {Error} If frameName already exists
+     */
+    addFrame: (frameName: FrameName, frameSchema: IFrameSchema) => void;
+    /**
+     * Validates the existence of a frame
+     * @public
+     * @throws {Error} If frameName is not found
+     * Memoized function to cache validation results
+     */
+    validate: (frameName: FrameName, source: string) => void;
+}
+
 declare const backtest: {
+    exchangeValidationService: ExchangeValidationService;
+    strategyValidationService: StrategyValidationService;
+    frameValidationService: FrameValidationService;
+    backtestMarkdownService: BacktestMarkdownService;
+    liveMarkdownService: LiveMarkdownService;
     backtestLogicPublicService: BacktestLogicPublicService;
     liveLogicPublicService: LiveLogicPublicService;
     backtestLogicPrivateService: BacktestLogicPrivateService;
@@ -443,4 +2588,4 @@ declare const backtest: {
     loggerService: LoggerService;
 };
 
-export { Backtest, type CandleInterval, ExecutionContextService, type FrameInterval, type ICandleData, type IExchangeSchema, type IFrameSchema, type IPersistBase, type ISignalDto, type ISignalRow, type IStrategyPnL, type IStrategySchema, type IStrategyTickResult, type IStrategyTickResultActive, type IStrategyTickResultClosed, type IStrategyTickResultIdle, type IStrategyTickResultOpened, Live, MethodContextService, PersistBase, PersistSignalAdaper, type SignalInterval, type TPersistBase, type TPersistBaseCtor, addExchange, addFrame, addStrategy, backtest, formatPrice, formatQuantity, getAveragePrice, getCandles, getDate, getMode, reduce, runBacktest, runBacktestGUI, setLogger, startRun, stopAll, stopRun };
+export { Backtest, type CandleInterval, ExecutionContextService, type FrameInterval, type ICandleData, type IExchangeSchema, type IFrameSchema, type IPersistBase, type ISignalDto, type ISignalRow, type IStrategyPnL, type IStrategySchema, type IStrategyTickResult, type IStrategyTickResultActive, type IStrategyTickResultClosed, type IStrategyTickResultIdle, type IStrategyTickResultOpened, Live, MethodContextService, PersistBase, PersistSignalAdaper, type SignalInterval, type TPersistBase, type TPersistBaseCtor, addExchange, addFrame, addStrategy, formatPrice, formatQuantity, getAveragePrice, getCandles, getDate, getMode, backtest as lib, listenError, listenSignal, listenSignalBacktest, listenSignalBacktestOnce, listenSignalLive, listenSignalLiveOnce, listenSignalOnce, setLogger };