backtest-kit 3.4.2 → 3.5.1

package/types.d.ts

@@ -58,2161 +58,1623 @@ declare const ExecutionContextService: (new () => {
 type TExecutionContextService = InstanceType<typeof ExecutionContextService>;
 
 /**
- * Single log entry stored in the log history.
+ * 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
  */
-interface ILogEntry {
-    /** Unique entry identifier generated via randomString */
-    id: string;
-    /** Log level */
-    type: "log" | "debug" | "info" | "warn";
-    /** Unix timestamp in milliseconds when the entry was created */
-    timestamp: number;
-    /** Date taken from backtest context to improve user experience */
-    createdAt: string;
-    /** Log topic / method name */
-    topic: string;
-    /** Additional arguments passed to the log call */
-    args: unknown[];
+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;
 }
 /**
- * Interface representing a logging mechanism for the swarm system.
- * Provides methods to record messages at different severity levels, used across components like agents, sessions, states, storage, swarms, history, embeddings, completions, and policies.
- * Logs are utilized to track lifecycle events (e.g., initialization, disposal), operational details (e.g., tool calls, message emissions), validation outcomes (e.g., policy checks), and errors (e.g., persistence failures), aiding in debugging, monitoring, and auditing.
-*/
-interface ILogger {
-    /**
-     * Logs a general-purpose message.
-     * Used throughout the swarm system to record significant events or state changes, such as agent execution, session connections, or storage updates.
-     */
-    log(topic: string, ...args: any[]): void;
-    /**
-     * Logs a debug-level message.
-     * Employed for detailed diagnostic information, such as intermediate states during agent tool calls, swarm navigation changes, or embedding creation processes, typically enabled in development or troubleshooting scenarios.
-     */
-    debug(topic: string, ...args: any[]): void;
-    /**
-     * Logs an info-level message.
-     * 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;
+ * Callbacks for frame lifecycle events.
+ */
+interface IFrameCallbacks {
     /**
-     * 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.
+     * 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
      */
-    warn(topic: string, ...args: any[]): void;
+    onTimeframe: (timeframe: Date[], startDate: Date, endDate: Date, interval: FrameInterval) => void | Promise<void>;
 }
-
 /**
- * Candle time interval for fetching historical data.
+ * 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`);
+ *     },
+ *   },
+ * });
+ * ```
  */
-type CandleInterval = "1m" | "3m" | "5m" | "15m" | "30m" | "1h" | "2h" | "4h" | "6h" | "8h";
-/** Numeric type that can be undefined (used for optional numeric values) */
-type Num = number | undefined;
-interface IPublicCandleData {
-    /** Unix timestamp in milliseconds when candle opened */
-    timestamp: Num;
-    /** Opening price at candle start */
-    open: Num;
-    /** Highest price during candle period */
-    high: Num;
-    /** Lowest price during candle period */
-    low: Num;
-    /** Closing price at candle end */
-    close: Num;
-    /** Trading volume during candle period */
-    volume: Num;
+interface IFrameSchema {
+    /** Unique identifier for this frame */
+    frameName: FrameName;
+    /** Optional developer note for documentation */
+    note?: string;
+    /** 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>;
 }
 /**
- * Single OHLCV candle data point.
- * Used for VWAP calculation and backtesting.
+ * Frame interface for timeframe generation.
+ * Used internally by backtest orchestration.
  */
-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;
+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, frameName: FrameName) => Promise<Date[]>;
 }
 /**
- * Single bid or ask in order book.
+ * Unique identifier for a frame schema.
+ * Used to retrieve frame instances via dependency injection.
  */
-interface IBidData {
-    /** Price level as string */
-    price: string;
-    /** Quantity at this price level as string */
-    quantity: string;
-}
+type FrameName = string;
+
 /**
- * Order book data containing bids and asks.
+ * Risk rejection result type.
+ * Can be void, null, or an IRiskRejectionResult object.
  */
-interface IOrderBookData {
-    /** Trading pair symbol */
+type RiskRejection = void | IRiskRejectionResult | string | null;
+/**
+ * Risk check arguments for evaluating whether to allow opening a new position.
+ * Called BEFORE signal creation to validate if conditions allow new signals.
+ * Contains only passthrough arguments from ClientStrategy context.
+ */
+interface IRiskCheckArgs {
+    /** Trading pair symbol (e.g., "BTCUSDT") */
     symbol: string;
-    /** Array of bid orders (buy orders) */
-    bids: IBidData[];
-    /** Array of ask orders (sell orders) */
-    asks: IBidData[];
+    /** Pending signal to apply */
+    currentSignal: IPublicSignalRow;
+    /** Strategy name requesting to open a position */
+    strategyName: StrategyName;
+    /** Exchange name */
+    exchangeName: ExchangeName;
+    /** Risk name */
+    riskName: RiskName;
+    /** Frame name */
+    frameName: FrameName;
+    /** Current VWAP price */
+    currentPrice: number;
+    /** Current timestamp */
+    timestamp: number;
 }
 /**
- * Aggregated trade data point.
- * Represents a single trade that has occurred, used for detailed analysis and backtesting.
- * Includes price, quantity, timestamp, and whether the buyer is the market maker (which can indicate trade direction).
- *
+ * Active position tracked by ClientRisk for cross-strategy analysis.
  */
-interface IAggregatedTradeData {
-    /** Unique identifier for the aggregated trade */
-    id: string;
-    /** Price at which the trade occurred */
-    price: number;
-    /** Quantity traded */
-    qty: number;
-    /** Unix timestamp in milliseconds when the trade occurred */
-    timestamp: number;
-    /** Whether the buyer is the market maker (true if buyer is maker, false if seller is maker) */
-    isBuyerMaker: boolean;
+interface IRiskActivePosition {
+    /** Strategy name owning the position */
+    strategyName: StrategyName;
+    /** Exchange name */
+    exchangeName: ExchangeName;
+    /** Frame name */
+    frameName: FrameName;
+    /** Trading pair symbol (e.g., "BTCUSDT") */
+    symbol: string;
+    /** Position direction ("long" or "short") */
+    position: "long" | "short";
+    /** Entry price */
+    priceOpen: number;
+    /** Stop loss price */
+    priceStopLoss: number;
+    /** Take profit price */
+    priceTakeProfit: number;
+    /** Estimated time in minutes */
+    minuteEstimatedTime: number;
+    /** Timestamp when the position was opened */
+    openTimestamp: number;
 }
 /**
- * Exchange parameters passed to ClientExchange constructor.
- * Combines schema with runtime dependencies.
- * Note: All exchange methods are required in params (defaults are applied during initialization).
+ * Optional callbacks for risk events.
  */
-interface IExchangeParams extends IExchangeSchema {
-    /** Logger service for debug output */
-    logger: ILogger;
-    /** Execution context service (symbol, when, backtest flag) */
-    execution: TExecutionContextService;
-    /** Fetch candles from data source (required, defaults applied) */
-    getCandles: (symbol: string, interval: CandleInterval, since: Date, limit: number, backtest: boolean) => Promise<ICandleData[]>;
-    /** Format quantity according to exchange precision rules (required, defaults applied) */
-    formatQuantity: (symbol: string, quantity: number, backtest: boolean) => Promise<string>;
-    /** Format price according to exchange precision rules (required, defaults applied) */
-    formatPrice: (symbol: string, price: number, backtest: boolean) => Promise<string>;
-    /** Fetch order book for a trading pair (required, defaults applied) */
-    getOrderBook: (symbol: string, depth: number, from: Date, to: Date, backtest: boolean) => Promise<IOrderBookData>;
-    /** Fetch aggregated trades for a trading pair (required, defaults applied) */
-    getAggregatedTrades: (symbol: string, from: Date, to: Date, backtest: boolean) => Promise<IAggregatedTradeData[]>;
+interface IRiskCallbacks {
+    /** Called when a signal is rejected due to risk limits */
+    onRejected: (symbol: string, params: IRiskCheckArgs) => void | Promise<void>;
+    /** Called when a signal passes risk checks */
+    onAllowed: (symbol: string, params: IRiskCheckArgs) => void | Promise<void>;
 }
 /**
- * Optional callbacks for exchange data events.
+ * Payload passed to risk validation functions.
+ * Extends IRiskCheckArgs with portfolio state data.
  */
-interface IExchangeCallbacks {
-    /** Called when candle data is fetched */
-    onCandleData: (symbol: string, interval: CandleInterval, since: Date, limit: number, data: ICandleData[]) => void | Promise<void>;
+interface IRiskValidationPayload extends IRiskCheckArgs {
+    /** Current signal being validated (IRiskSignalRow is calculated internally so priceOpen always exist) */
+    currentSignal: IRiskSignalRow;
+    /** Number of currently active positions across all strategies */
+    activePositionCount: number;
+    /** List of currently active positions across all strategies */
+    activePositions: IRiskActivePosition[];
 }
 /**
- * Exchange schema registered via addExchange().
- * Defines candle data source and formatting logic.
+ * Risk validation rejection result.
+ * Returned when validation fails, contains debugging information.
  */
-interface IExchangeSchema {
-    /** Unique exchange identifier for registration */
-    exchangeName: ExchangeName;
+interface IRiskRejectionResult {
+    /** Unique identifier for this rejection instance */
+    id: string | null;
+    /** Human-readable reason for rejection */
+    note: string;
+}
+/**
+ * Risk validation function type.
+ * Returns null/void if validation passes, IRiskRejectionResult if validation fails.
+ * Can also throw error which will be caught and converted to IRiskRejectionResult.
+ */
+interface IRiskValidationFn {
+    (payload: IRiskValidationPayload): RiskRejection | Promise<RiskRejection>;
+}
+/**
+ * Risk validation configuration.
+ * Defines validation logic with optional documentation.
+ */
+interface IRiskValidation {
+    /**
+     * The validation function to apply to the risk check parameters.
+     */
+    validate: IRiskValidationFn;
+    /**
+     * Optional description for documentation purposes.
+     * Aids in understanding the purpose or behavior of the validation.
+     */
+    note?: string;
+}
+/**
+ * Risk schema registered via addRisk().
+ * Defines portfolio-level risk controls via custom validations.
+ */
+interface IRiskSchema {
+    /** Unique risk profile identifier */
+    riskName: RiskName;
     /** Optional developer note for documentation */
     note?: string;
+    /** Optional lifecycle event callbacks (onRejected, onAllowed) */
+    callbacks?: Partial<IRiskCallbacks>;
+    /** Custom validations array for risk logic */
+    validations: (IRiskValidation | IRiskValidationFn)[];
+}
+/**
+ * Risk parameters passed to ClientRisk constructor.
+ * Combines schema with runtime dependencies and emission callbacks.
+ */
+interface IRiskParams extends IRiskSchema {
+    /** Exchange name (e.g., "binance") */
+    exchangeName: ExchangeName;
+    /** Logger service for debug output */
+    logger: ILogger;
+    /** True if backtest mode, false if live mode */
+    backtest: boolean;
     /**
-     * Fetch candles from data source (API or database).
+     * Callback invoked when a signal is rejected due to risk limits.
+     * Called before emitting to riskSubject.
+     * Used for event emission to riskSubject (separate from schema callbacks).
      *
-     * @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
-     * @param backtest - Whether running in backtest mode
-     * @returns Promise resolving to array of OHLCV candle data
+     * @param symbol - Trading pair symbol
+     * @param params - Risk check arguments
+     * @param activePositionCount - Number of active positions at rejection time
+     * @param rejectionResult - Rejection result with id and note
+     * @param timestamp - Event timestamp in milliseconds
+     * @param backtest - True if backtest mode, false if live mode
      */
-    getCandles: (symbol: string, interval: CandleInterval, since: Date, limit: number, backtest: boolean) => Promise<IPublicCandleData[]>;
+    onRejected: (symbol: string, params: IRiskCheckArgs, activePositionCount: number, rejectionResult: IRiskRejectionResult, timestamp: number, backtest: boolean) => void | Promise<void>;
+}
+/**
+ * Risk interface implemented by ClientRisk.
+ * Provides risk checking for signals and position tracking.
+ */
+interface IRisk {
     /**
-     * Format quantity according to exchange precision rules.
+     * Check if a signal should be allowed based on risk limits.
      *
-     * Optional. If not provided, defaults to Bitcoin precision on Binance (8 decimal places).
+     * @param params - Risk check arguments (position size, portfolio state, etc.)
+     * @returns Promise resolving to risk check result
+     */
+    checkSignal: (params: IRiskCheckArgs) => Promise<boolean>;
+    /**
+     * Register a new opened signal/position.
      *
      * @param symbol - Trading pair symbol
-     * @param quantity - Raw quantity value
-     * @param backtest - Whether running in backtest mode
-     * @returns Promise resolving to formatted quantity string
+     * @param context - Context information (strategyName, riskName, exchangeName, frameName)
+     * @param positionData - Position data (position, prices, timing)
      */
-    formatQuantity?: (symbol: string, quantity: number, backtest: boolean) => Promise<string>;
+    addSignal: (symbol: string, context: {
+        strategyName: StrategyName;
+        riskName: RiskName;
+        exchangeName: ExchangeName;
+        frameName: FrameName;
+    }, positionData: {
+        position: "long" | "short";
+        priceOpen: number;
+        priceStopLoss: number;
+        priceTakeProfit: number;
+        minuteEstimatedTime: number;
+        openTimestamp: number;
+    }) => Promise<void>;
     /**
-     * Format price according to exchange precision rules.
-     *
-     * Optional. If not provided, defaults to Bitcoin precision on Binance (2 decimal places).
+     * Remove a closed signal/position.
      *
      * @param symbol - Trading pair symbol
-     * @param price - Raw price value
-     * @param backtest - Whether running in backtest mode
-     * @returns Promise resolving to formatted price string
+     * @param context - Context information (strategyName, riskName, exchangeName, frameName)
      */
-    formatPrice?: (symbol: string, price: number, backtest: boolean) => Promise<string>;
+    removeSignal: (symbol: string, context: {
+        strategyName: StrategyName;
+        riskName: RiskName;
+        exchangeName: ExchangeName;
+        frameName: FrameName;
+    }) => Promise<void>;
+}
+/**
+ * Unique risk profile identifier.
+ */
+type RiskName = string;
+
+/**
+ * Profit or loss level milestone in percentage points.
+ * Represents 10%, 20%, 30%, ..., 100% profit or loss thresholds.
+ *
+ * Used to track when a signal reaches specific profit/loss milestones.
+ * Each level is emitted only once per signal (deduplication via Set).
+ *
+ * @example
+ * ```typescript
+ * const level: PartialLevel = 50; // 50% profit or loss milestone
+ * ```
+ */
+type PartialLevel = 10 | 20 | 30 | 40 | 50 | 60 | 70 | 80 | 90 | 100;
+/**
+ * Serializable partial data for persistence layer.
+ * Converts Sets to arrays for JSON serialization.
+ *
+ * Stored in PersistPartialAdapter as Record<signalId, IPartialData>.
+ * Loaded on initialization and converted back to IPartialState.
+ */
+interface IPartialData {
     /**
-     * Fetch order book for a trading pair.
+     * Array of profit levels that have been reached for this signal.
+     * Serialized form of IPartialState.profitLevels Set.
+     */
+    profitLevels: PartialLevel[];
+    /**
+     * Array of loss levels that have been reached for this signal.
+     * Serialized form of IPartialState.lossLevels Set.
+     */
+    lossLevels: PartialLevel[];
+}
+/**
+ * Partial profit/loss tracking interface.
+ * Implemented by ClientPartial and PartialConnectionService.
+ *
+ * Tracks profit/loss level milestones for active trading signals.
+ * Emits events when signals reach 10%, 20%, 30%, etc profit or loss.
+ *
+ * @example
+ * ```typescript
+ * import { ClientPartial } from "./client/ClientPartial";
+ *
+ * const partial = new ClientPartial({
+ *   logger: loggerService,
+ *   onProfit: (symbol, data, price, level, backtest, timestamp) => {
+ *     console.log(`Signal ${data.id} reached ${level}% profit`);
+ *   },
+ *   onLoss: (symbol, data, price, level, backtest, timestamp) => {
+ *     console.log(`Signal ${data.id} reached ${level}% loss`);
+ *   }
+ * });
+ *
+ * await partial.waitForInit("BTCUSDT");
+ *
+ * // During signal monitoring
+ * await partial.profit("BTCUSDT", signal, 51000, 15.5, false, new Date());
+ * // Emits event when reaching 10% profit milestone
+ *
+ * // When signal closes
+ * await partial.clear("BTCUSDT", signal, 52000);
+ * ```
+ */
+interface IPartial {
+    /**
+     * Processes profit state and emits events for new profit levels reached.
      *
-     * Optional. If not provided, throws an error when called.
+     * Called by ClientStrategy during signal monitoring when revenuePercent > 0.
+     * Checks which profit levels (10%, 20%, 30%, etc) have been reached
+     * and emits events for new levels only (Set-based deduplication).
      *
      * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
-     * @param depth - Maximum depth levels for both bids and asks (default: CC_ORDER_BOOK_MAX_DEPTH_LEVELS)
-     * @param from - Start of time range (used in backtest for historical data, can be ignored in live)
-     * @param to - End of time range (used in backtest for historical data, can be ignored in live)
-     * @param backtest - Whether running in backtest mode
-     * @returns Promise resolving to order book data
+     * @param data - Signal row data
+     * @param currentPrice - Current market price
+     * @param revenuePercent - Current profit percentage (positive value)
+     * @param backtest - True if backtest mode, false if live mode
+     * @param when - Event timestamp (current time for live, candle time for backtest)
+     * @returns Promise that resolves when profit processing is complete
      *
      * @example
      * ```typescript
-     * // Backtest implementation: returns historical order book for the time range
-     * const backtestOrderBook = async (symbol: string, depth: number, from: Date, to: Date, backtest: boolean) => {
-     *   if (backtest) {
-     *     return await database.getOrderBookSnapshot(symbol, depth, from, to);
-     *   }
-     *   return await exchange.fetchOrderBook(symbol, depth);
-     * };
+     * // Signal opened at $50000, current price $51500
+     * // Revenue: 3% profit
+     * await partial.profit("BTCUSDT", signal, 51500, 3.0, false, new Date());
+     * // No events emitted (below 10% threshold)
      *
-     * // Live implementation: ignores from/to when not in backtest mode
-     * const liveOrderBook = async (symbol: string, depth: number, _from: Date, _to: Date, backtest: boolean) => {
-     *   return await exchange.fetchOrderBook(symbol, depth);
-     * };
+     * // Price rises to $55000
+     * // Revenue: 10% profit
+     * await partial.profit("BTCUSDT", signal, 55000, 10.0, false, new Date());
+     * // Emits partialProfitSubject event for 10% level
+     *
+     * // Price rises to $61000
+     * // Revenue: 22% profit
+     * await partial.profit("BTCUSDT", signal, 61000, 22.0, false, new Date());
+     * // Emits events for 20% level only (10% already emitted)
      * ```
      */
-    getOrderBook?: (symbol: string, depth: number, from: Date, to: Date, backtest: boolean) => Promise<IOrderBookData>;
+    profit(symbol: string, data: IPublicSignalRow, currentPrice: number, revenuePercent: number, backtest: boolean, when: Date): Promise<void>;
     /**
-     * Fetch aggregated trades for a trading pair.
-     * Optional. If not provided, throws an error when called.
+     * Processes loss state and emits events for new loss levels reached.
+     *
+     * Called by ClientStrategy during signal monitoring when revenuePercent < 0.
+     * Checks which loss levels (10%, 20%, 30%, etc) have been reached
+     * and emits events for new levels only (Set-based deduplication).
+     *
      * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
-     * @param from - Start of time range (used in backtest for historical data, can be ignored in live)
-     * @param to - End of time range (used in backtest for historical data, can be ignored in live)
-     * @param backtest - Whether running in backtest mode
-     * @return Promise resolving to array of aggregated trade data
+     * @param data - Signal row data
+     * @param currentPrice - Current market price
+     * @param lossPercent - Current loss percentage (negative value)
+     * @param backtest - True if backtest mode, false if live mode
+     * @param when - Event timestamp (current time for live, candle time for backtest)
+     * @returns Promise that resolves when loss processing is complete
+     *
      * @example
      * ```typescript
-     * // Backtest implementation: returns historical aggregated trades for the time range
-     * const backtestAggregatedTrades = async (symbol: string, from: Date, to: Date, backtest: boolean) => {
-     *   if (backtest) {
-     *     return await database.getAggregatedTrades(symbol, from, to);
-     *   }
-     *   return await exchange.fetchAggregatedTrades(symbol);
-     * };
+     * // Signal opened at $50000, current price $48000
+     * // Loss: -4% loss
+     * await partial.loss("BTCUSDT", signal, 48000, -4.0, false, new Date());
+     * // No events emitted (below -10% threshold)
      *
-     * // Live implementation: ignores from/to when not in backtest mode
-     * const liveAggregatedTrades = async (symbol: string, _from: Date, _to: Date, backtest: boolean) => {
-     *   return await exchange.fetchAggregatedTrades(symbol);
-     * };
+     * // Price drops to $45000
+     * // Loss: -10% loss
+     * await partial.loss("BTCUSDT", signal, 45000, -10.0, false, new Date());
+     * // Emits partialLossSubject event for 10% level
+     *
+     * // Price drops to $39000
+     * // Loss: -22% loss
+     * await partial.loss("BTCUSDT", signal, 39000, -22.0, false, new Date());
+     * // Emits events for 20% level only (10% already emitted)
      * ```
      */
-    getAggregatedTrades?: (symbol: string, from: Date, to: Date, backtest: boolean) => Promise<IAggregatedTradeData[]>;
-    /** Optional lifecycle event callbacks (onCandleData) */
-    callbacks?: Partial<IExchangeCallbacks>;
-}
-/**
- * Exchange interface implemented by ClientExchange.
- * Provides candle data access and VWAP calculation.
- */
-interface IExchange {
+    loss(symbol: string, data: IPublicSignalRow, currentPrice: number, lossPercent: number, backtest: boolean, when: Date): Promise<void>;
     /**
-     * Fetch historical candles backwards from execution context time.
+     * Clears partial profit/loss state when signal closes.
      *
-     * @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).
+     * Called by ClientStrategy when signal completes (TP/SL/time_expired).
+     * Removes signal state from memory and persists changes to disk.
+     * Cleans up memoized ClientPartial instance in PartialConnectionService.
      *
      * @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 data - Signal row data
+     * @param priceClose - Final closing price
+     * @returns Promise that resolves when clear is complete
      *
-     * @param symbol - Trading pair symbol
-     * @param quantity - Raw quantity value
-     * @returns Promise resolving to formatted quantity string
+     * @example
+     * ```typescript
+     * // Signal closes at take profit
+     * await partial.clear("BTCUSDT", signal, 52000);
+     * // State removed from _states Map
+     * // Persisted to disk without this signal's data
+     * // Memoized instance cleared from getPartial cache
+     * ```
      */
-    formatQuantity: (symbol: string, quantity: number) => Promise<string>;
+    clear(symbol: string, data: IPublicSignalRow, priceClose: number, backtest: boolean): Promise<void>;
+}
+
+/**
+ * Serializable breakeven data for persistence layer.
+ * Converts state to simple boolean for JSON serialization.
+ *
+ * Stored in PersistBreakevenAdapter as Record<signalId, IBreakevenData>.
+ * Loaded on initialization and converted back to IBreakevenState.
+ */
+interface IBreakevenData {
     /**
-     * Format price for exchange precision.
-     *
-     * @param symbol - Trading pair symbol
-     * @param price - Raw price value
-     * @returns Promise resolving to formatted price string
+     * Whether breakeven has been reached for this signal.
+     * Serialized form of IBreakevenState.reached.
      */
-    formatPrice: (symbol: string, price: number) => Promise<string>;
+    reached: boolean;
+}
+/**
+ * Breakeven tracking interface.
+ * Implemented by ClientBreakeven and BreakevenConnectionService.
+ *
+ * Tracks when a signal's stop-loss is moved to breakeven (entry price).
+ * Emits events when threshold is reached (price moves far enough to cover transaction costs).
+ *
+ * @example
+ * ```typescript
+ * import { ClientBreakeven } from "./client/ClientBreakeven";
+ *
+ * const breakeven = new ClientBreakeven({
+ *   logger: loggerService,
+ *   onBreakeven: (symbol, data, price, backtest, timestamp) => {
+ *     console.log(`Signal ${data.id} reached breakeven at ${price}`);
+ *   }
+ * });
+ *
+ * await breakeven.waitForInit("BTCUSDT");
+ *
+ * // During signal monitoring
+ * await breakeven.check("BTCUSDT", signal, 100.5, false, new Date());
+ * // Emits event when threshold reached and SL moved to entry
+ *
+ * // When signal closes
+ * await breakeven.clear("BTCUSDT", signal, 101, false);
+ * ```
+ */
+interface IBreakeven {
     /**
-     * Calculate VWAP from last 5 1-minute candles.
+     * Checks if breakeven should be triggered and emits event if conditions met.
      *
-     * Formula: VWAP = Σ(Typical Price × Volume) / Σ(Volume)
-     * where Typical Price = (High + Low + Close) / 3
+     * Called by ClientStrategy during signal monitoring.
+     * Checks if:
+     * 1. Breakeven not already reached
+     * 2. Price has moved far enough to cover transaction costs
+     * 3. Stop-loss can be moved to entry price
      *
-     * @param symbol - Trading pair symbol
-     * @returns Promise resolving to volume-weighted average price
-     */
-    getAveragePrice: (symbol: string) => Promise<number>;
-    /**
-     * Fetch order book for a trading pair.
+     * If all conditions met:
+     * - Marks breakeven as reached
+     * - Calls onBreakeven callback (emits to breakevenSubject)
+     * - Persists state to disk
      *
      * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
-     * @param depth - Maximum depth levels (default: CC_ORDER_BOOK_MAX_DEPTH_LEVELS)
-     * @returns Promise resolving to order book data
-     */
-    getOrderBook: (symbol: string, depth?: number) => Promise<IOrderBookData>;
-    /**
-     * Fetch aggregated trades for a trading pair.
+     * @param data - Signal row data
+     * @param currentPrice - Current market price
+     * @param backtest - True if backtest mode, false if live mode
+     * @param when - Event timestamp (current time for live, candle time for backtest)
+     * @returns Promise that resolves when breakeven check is complete
      *
-     * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
-     * @param limit - Optional maximum number of aggregated trades to fetch. If empty returns one hour of data.
-     * @returns Promise resolving to array of aggregated trade data
+     * @example
+     * ```typescript
+     * // LONG: entry=100, slippage=0.1%, fee=0.1%, threshold=0.4%
+     * // Price at 100.3 - threshold not reached
+     * await breakeven.check("BTCUSDT", signal, 100.3, false, new Date());
+     * // No event emitted (price < 100.4)
+     *
+     * // Price at 100.5 - threshold reached!
+     * await breakeven.check("BTCUSDT", signal, 100.5, false, new Date());
+     * // Emits breakevenSubject event
+     *
+     * // Price at 101 - already at breakeven
+     * await breakeven.check("BTCUSDT", signal, 101, false, new Date());
+     * // No event emitted (already reached)
+     * ```
      */
-    getAggregatedTrades: (symbol: string, limit?: number) => Promise<IAggregatedTradeData[]>;
+    check(symbol: string, data: IPublicSignalRow, currentPrice: number, backtest: boolean, when: Date): Promise<boolean>;
     /**
-     * Fetch raw candles with flexible date/limit parameters.
-     *
-     * All modes respect execution context and prevent look-ahead bias.
+     * Clears breakeven state when signal closes.
      *
-     * Parameter combinations:
-     * 1. sDate + eDate + limit: fetches with explicit parameters, validates eDate <= when
-     * 2. sDate + eDate: calculates limit from date range, validates eDate <= when
-     * 3. eDate + limit: calculates sDate backward, validates eDate <= when
-     * 4. sDate + limit: fetches forward, validates calculated endTimestamp <= when
-     * 5. Only limit: uses execution.context.when as reference (backward)
+     * Called by ClientStrategy when signal completes (TP/SL/time_expired).
+     * Removes signal state from memory and persists changes to disk.
+     * Cleans up memoized ClientBreakeven instance in BreakevenConnectionService.
      *
      * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
-     * @param interval - Candle interval (e.g., "1m", "1h")
-     * @param limit - Optional number of candles to fetch
-     * @param sDate - Optional start date in milliseconds
-     * @param eDate - Optional end date in milliseconds
-     * @returns Promise resolving to array of candles
+     * @param data - Signal row data
+     * @param priceClose - Final closing price
+     * @param backtest - True if backtest mode, false if live mode
+     * @returns Promise that resolves when clear is complete
+     *
+     * @example
+     * ```typescript
+     * // Signal closes at take profit
+     * await breakeven.clear("BTCUSDT", signal, 101);
+     * // State removed from _states Map
+     * // Persisted to disk without this signal's data
+     * // Memoized instance cleared from getBreakeven cache
+     * ```
      */
-    getRawCandles: (symbol: string, interval: CandleInterval, limit?: number, sDate?: number, eDate?: number) => Promise<ICandleData[]>;
+    clear(symbol: string, data: IPublicSignalRow, priceClose: number, backtest: boolean): Promise<void>;
 }
-/**
- * Unique exchange identifier.
- */
-type ExchangeName = string;
 
 /**
- * Parameters for pre-caching candles into persist storage.
- * Used to download historical candle data before running a backtest.
+ * Contract for breakeven events.
+ *
+ * Emitted by breakevenSubject when a signal's stop-loss is moved to breakeven (entry price).
+ * Used for tracking risk reduction milestones and monitoring strategy safety.
+ *
+ * Events are emitted only once per signal (idempotent - protected by ClientBreakeven state).
+ * Breakeven is triggered when price moves far enough in profit direction to cover transaction costs.
+ *
+ * Consumers:
+ * - BreakevenMarkdownService: Accumulates events for report generation
+ * - User callbacks via listenBreakeven() / listenBreakevenOnce()
+ *
+ * @example
+ * ```typescript
+ * import { listenBreakeven } from "backtest-kit";
+ *
+ * // Listen to all breakeven events
+ * listenBreakeven((event) => {
+ *   console.log(`[${event.backtest ? "Backtest" : "Live"}] Signal ${event.data.id} moved to breakeven`);
+ *   console.log(`Symbol: ${event.symbol}, Price: ${event.currentPrice}`);
+ *   console.log(`Position: ${event.data.position}, Entry: ${event.data.priceOpen}`);
+ *   console.log(`Original SL: ${event.data.priceStopLoss}, New SL: ${event.data.priceOpen}`);
+ * });
+ *
+ * // Wait for specific signal to reach breakeven
+ * listenBreakevenOnce(
+ *   (event) => event.data.id === "target-signal-id",
+ *   (event) => console.log("Signal reached breakeven:", event.data.id)
+ * );
+ * ```
  */
-interface ICacheCandlesParams {
-    /** Trading pair symbol (e.g., "BTCUSDT") */
+interface BreakevenContract {
+    /**
+     * Trading pair symbol (e.g., "BTCUSDT").
+     * Identifies which market this breakeven event belongs to.
+     */
     symbol: string;
-    /** Name of the registered exchange schema */
+    /**
+     * Strategy name that generated this signal.
+     * Identifies which strategy execution this breakeven event belongs to.
+     */
+    strategyName: StrategyName;
+    /**
+     * Exchange name where this signal is being executed.
+     * Identifies which exchange this breakeven event belongs to.
+     */
     exchangeName: ExchangeName;
-    /** Candle time interval (e.g., "1m", "4h") */
-    interval: CandleInterval;
-    /** Start date of the caching range (inclusive) */
-    from: Date;
-    /** End date of the caching range (inclusive) */
-    to: Date;
-}
-/**
- * Parameters for validating cached candle timestamps.
- * Reads JSON files directly from persist storage directory.
- */
-interface ICheckCandlesParams {
-    /** Trading pair symbol (e.g., "BTCUSDT") */
-    symbol: string;
-    /** Name of the registered exchange schema */
-    exchangeName: ExchangeName;
-    /** Candle time interval (e.g., "1m", "4h") */
-    interval: CandleInterval;
-    /** Start date of the validation range (inclusive) */
-    from: Date;
-    /** End date of the validation range (inclusive) */
-    to: Date;
-    /** Base directory of candle persist storage (default: "./dump/data/candle") */
-    baseDir?: string;
+    /**
+     * Frame name where this signal is being executed.
+     * Identifies which frame this breakeven event belongs to (empty string for live mode).
+     */
+    frameName: FrameName;
+    /**
+     * Complete signal row data with original prices.
+     * Contains all signal information including originalPriceStopLoss, originalPriceTakeProfit, and partialExecuted.
+     */
+    data: IPublicSignalRow;
+    /**
+     * Current market price at which breakeven was triggered.
+     * Used to verify threshold calculation.
+     */
+    currentPrice: number;
+    /**
+     * Execution mode flag.
+     * - true: Event from backtest execution (historical candle data)
+     * - false: Event from live trading (real-time tick)
+     */
+    backtest: boolean;
+    /**
+     * Event timestamp in milliseconds since Unix epoch.
+     *
+     * Timing semantics:
+     * - Live mode: when.getTime() at the moment breakeven was set
+     * - Backtest mode: candle.timestamp of the candle that triggered breakeven
+     *
+     * @example
+     * ```typescript
+     * const eventDate = new Date(event.timestamp);
+     * console.log(`Breakeven set at: ${eventDate.toISOString()}`);
+     * ```
+     */
+    timestamp: number;
 }
+
 /**
- * Checks cached candle timestamps for correct interval alignment.
- * Reads JSON files directly from persist storage without using abstractions.
+ * Contract for partial profit level events.
  *
- * @param params - Validation parameters
- */
-declare function checkCandles(params: ICheckCandlesParams): Promise<void>;
-/**
- * Pre-caches candles for a date range into persist storage.
- * Downloads all candles matching the interval from `from` to `to`.
+ * Emitted by partialProfitSubject when a signal reaches a profit level milestone (10%, 20%, 30%, etc).
+ * Used for tracking partial take-profit execution and monitoring strategy performance.
  *
- * @param params - Cache parameters
- */
-declare function warmCandles(params: ICacheCandlesParams): Promise<void>;
-
-/**
- * Type alias for enum objects with string key-value pairs
- */
-type Enum = Record<string, string>;
-/**
- * Type alias for ValidateArgs with any enum type
- */
-type Args = ValidateArgs<any>;
-/**
- * Interface defining validation arguments for all entity types.
+ * Events are emitted only once per level per signal (Set-based deduplication in ClientPartial).
+ * Multiple levels can be emitted in a single tick if price jumps significantly.
  *
- * Each property accepts an enum object where values will be validated
- * against registered entities in their respective validation services.
+ * Consumers:
+ * - PartialMarkdownService: Accumulates events for report generation
+ * - User callbacks via listenPartialProfit() / listenPartialProfitOnce()
  *
- * @template T - Enum type extending Record<string, string>
+ * @example
+ * ```typescript
+ * import { listenPartialProfit } from "backtest-kit";
+ *
+ * // Listen to all partial profit events
+ * listenPartialProfit((event) => {
+ *   console.log(`[${event.backtest ? "Backtest" : "Live"}] Signal ${event.data.id} reached ${event.level}% profit`);
+ *   console.log(`Symbol: ${event.symbol}, Price: ${event.currentPrice}`);
+ *   console.log(`Position: ${event.data.position}, Entry: ${event.data.priceOpen}`);
+ * });
+ *
+ * // Wait for first 50% profit level
+ * listenPartialProfitOnce(
+ *   (event) => event.level === 50,
+ *   (event) => console.log("50% profit reached:", event.data.id)
+ * );
+ * ```
  */
-interface ValidateArgs<T = Enum> {
+interface PartialProfitContract {
     /**
-     * Exchange name enum to validate
-     * @example { BINANCE: "binance", BYBIT: "bybit" }
+     * Trading pair symbol (e.g., "BTCUSDT").
+     * Identifies which market this profit event belongs to.
      */
-    ExchangeName?: T;
+    symbol: string;
     /**
-     * Frame (timeframe) name enum to validate
-     * @example { Q1_2024: "2024-Q1", Q2_2024: "2024-Q2" }
+     * Strategy name that generated this signal.
+     * Identifies which strategy execution this profit event belongs to.
      */
-    FrameName?: T;
+    strategyName: StrategyName;
     /**
-     * Strategy name enum to validate
-     * @example { MOMENTUM_BTC: "momentum-btc" }
+     * Exchange name where this signal is being executed.
+     * Identifies which exchange this profit event belongs to.
      */
-    StrategyName?: T;
+    exchangeName: ExchangeName;
     /**
-     * Risk profile name enum to validate
-     * @example { CONSERVATIVE: "conservative", AGGRESSIVE: "aggressive" }
+     * Frame name where this signal is being executed.
+     * Identifies which frame this profit event belongs to (empty string for live mode).
      */
-    RiskName?: T;
+    frameName: FrameName;
     /**
-     * Action handler name enum to validate
-     * @example { TELEGRAM_NOTIFIER: "telegram-notifier" }
+     * Complete signal row data with original prices.
+     * Contains all signal information including originalPriceStopLoss, originalPriceTakeProfit, and partialExecuted.
      */
-    ActionName?: T;
+    data: IPublicSignalRow;
     /**
-     * Sizing strategy name enum to validate
-     * @example { FIXED_1000: "fixed-1000" }
+     * Current market price at which this profit level was reached.
+     * Used to calculate actual profit percentage.
      */
-    SizingName?: T;
+    currentPrice: number;
     /**
-     * Walker (parameter sweep) name enum to validate
-     * @example { RSI_SWEEP: "rsi-sweep" }
+     * Profit level milestone reached (10, 20, 30, 40, 50, 60, 70, 80, 90, or 100).
+     * Represents percentage profit relative to entry price.
+     *
+     * @example
+     * ```typescript
+     * // If entry was $50000 and level is 20:
+     * // currentPrice >= $60000 (20% profit)
+     * ```
      */
-    WalkerName?: T;
+    level: PartialLevel;
+    /**
+     * Execution mode flag.
+     * - true: Event from backtest execution (historical candle data)
+     * - false: Event from live trading (real-time tick)
+     */
+    backtest: boolean;
+    /**
+     * Event timestamp in milliseconds since Unix epoch.
+     *
+     * Timing semantics:
+     * - Live mode: when.getTime() at the moment profit level was detected
+     * - Backtest mode: candle.timestamp of the candle that triggered the level
+     *
+     * @example
+     * ```typescript
+     * const eventDate = new Date(event.timestamp);
+     * console.log(`Profit reached at: ${eventDate.toISOString()}`);
+     * ```
+     */
+    timestamp: number;
 }
+
 /**
- * Validates the existence of all provided entity names across validation services.
- *
- * This function accepts enum objects for various entity types (exchanges, frames,
- * strategies, risks, sizings, walkers) and validates that each entity
- * name exists in its respective registry. Validation results are memoized for performance.
- *
- * If no arguments are provided (or specific entity types are omitted), the function
- * automatically fetches and validates ALL registered entities from their respective
- * validation services. This is useful for comprehensive validation of the entire setup.
+ * Contract for partial loss level events.
  *
- * Use this before running backtests or optimizations to ensure all referenced
- * entities are properly registered and configured.
+ * Emitted by partialLossSubject when a signal reaches a loss level milestone (-10%, -20%, -30%, etc).
+ * Used for tracking partial stop-loss execution and monitoring strategy drawdown.
  *
- * @public
- * @param args - Partial validation arguments containing entity name enums to validate.
- *                If empty or omitted, validates all registered entities.
- * @throws {Error} If any entity name is not found in its validation service
+ * Events are emitted only once per level per signal (Set-based deduplication in ClientPartial).
+ * Multiple levels can be emitted in a single tick if price drops significantly.
  *
- * @example
- * ```typescript
- * // Validate ALL registered entities (exchanges, frames, strategies, etc.)
- * await validate({});
- * ```
+ * Consumers:
+ * - PartialMarkdownService: Accumulates events for report generation
+ * - User callbacks via listenPartialLoss() / listenPartialLossOnce()
  *
  * @example
  * ```typescript
- * // Define your entity name enums
- * enum ExchangeName {
- *   BINANCE = "binance",
- *   BYBIT = "bybit"
- * }
+ * import { listenPartialLoss } from "backtest-kit";
  *
- * enum StrategyName {
- *   MOMENTUM_BTC = "momentum-btc"
- * }
+ * // Listen to all partial loss events
+ * listenPartialLoss((event) => {
+ *   console.log(`[${event.backtest ? "Backtest" : "Live"}] Signal ${event.data.id} reached -${event.level}% loss`);
+ *   console.log(`Symbol: ${event.symbol}, Price: ${event.currentPrice}`);
+ *   console.log(`Position: ${event.data.position}, Entry: ${event.data.priceOpen}`);
  *
- * // Validate specific entities before running backtest
- * await validate({
- *   ExchangeName,
- *   StrategyName,
+ *   // Alert on significant loss
+ *   if (event.level >= 30 && !event.backtest) {
+ *     console.warn("HIGH LOSS ALERT:", event.data.id);
+ *   }
  * });
- * ```
  *
- * @example
- * ```typescript
- * // Validate specific entity types
- * await validate({
- *   RiskName: { CONSERVATIVE: "conservative" },
- *   SizingName: { FIXED_1000: "fixed-1000" },
- * });
+ * // Wait for first 20% loss level
+ * listenPartialLossOnce(
+ *   (event) => event.level === 20,
+ *   (event) => console.log("20% loss reached:", event.data.id)
+ * );
  * ```
  */
-declare function validate(args?: Partial<Args>): Promise<void>;
-
-/**
- * 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 {
+interface PartialLossContract {
     /**
-     * Called after timeframe array generation.
-     * Useful for logging or validating the generated timeframes.
+     * Trading pair symbol (e.g., "BTCUSDT").
+     * Identifies which market this loss event belongs to.
+     */
+    symbol: string;
+    /**
+     * Strategy name that generated this signal.
+     * Identifies which strategy execution this loss event belongs to.
+     */
+    strategyName: StrategyName;
+    /**
+     * Exchange name where this signal is being executed.
+     * Identifies which exchange this loss event belongs to.
+     */
+    exchangeName: ExchangeName;
+    /**
+     * Frame name where this signal is being executed.
+     * Identifies which frame this loss event belongs to (empty string for live mode).
+     */
+    frameName: FrameName;
+    /**
+     * Complete signal row data with original prices.
+     * Contains all signal information including originalPriceStopLoss, originalPriceTakeProfit, and partialExecuted.
+     */
+    data: IPublicSignalRow;
+    /**
+     * Current market price at which this loss level was reached.
+     * Used to calculate actual loss percentage.
+     */
+    currentPrice: number;
+    /**
+     * Loss level milestone reached (10, 20, 30, 40, 50, 60, 70, 80, 90, or 100).
+     * Represents percentage loss relative to entry price (absolute value).
      *
-     * @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
+     * Note: Stored as positive number, but represents negative loss.
+     * level=20 means -20% loss from entry price.
+     *
+     * @example
+     * ```typescript
+     * // If entry was $50000 and level is 20:
+     * // currentPrice <= $40000 (-20% loss)
+     * // Level is stored as 20, not -20
+     * ```
      */
-    onTimeframe: (timeframe: Date[], startDate: Date, endDate: Date, interval: FrameInterval) => void | Promise<void>;
+    level: PartialLevel;
+    /**
+     * Execution mode flag.
+     * - true: Event from backtest execution (historical candle data)
+     * - false: Event from live trading (real-time tick)
+     */
+    backtest: boolean;
+    /**
+     * Event timestamp in milliseconds since Unix epoch.
+     *
+     * Timing semantics:
+     * - Live mode: when.getTime() at the moment loss level was detected
+     * - Backtest mode: candle.timestamp of the candle that triggered the level
+     *
+     * @example
+     * ```typescript
+     * const eventDate = new Date(event.timestamp);
+     * console.log(`Loss reached at: ${eventDate.toISOString()}`);
+     *
+     * // Calculate time in loss
+     * const entryTime = event.data.pendingAt;
+     * const timeInLoss = event.timestamp - entryTime;
+     * console.log(`In loss for ${timeInLoss / 1000 / 60} minutes`);
+     * ```
+     */
+    timestamp: number;
 }
+
 /**
- * Frame schema registered via addFrame().
- * Defines backtest period and interval for timestamp generation.
+ * Contract for schedule ping events during scheduled signal monitoring.
+ *
+ * Emitted by schedulePingSubject every minute when a scheduled signal is being monitored.
+ * Used for tracking scheduled signal lifecycle and custom monitoring logic.
+ *
+ * Events are emitted only when scheduled signal is active (not cancelled, not activated).
+ * Allows users to implement custom cancellation logic via onSchedulePing callback.
+ *
+ * Consumers:
+ * - User callbacks via listenSchedulePing() / listenSchedulePingOnce()
  *
  * @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`);
- *     },
- *   },
+ * import { listenSchedulePing } from "backtest-kit";
+ *
+ * // Listen to all schedule ping events
+ * listenSchedulePing((event) => {
+ *   console.log(`[${event.backtest ? "Backtest" : "Live"}] Schedule Ping for ${event.symbol}`);
+ *   console.log(`Strategy: ${event.strategyName}, Exchange: ${event.exchangeName}`);
+ *   console.log(`Signal ID: ${event.data.id}, priceOpen: ${event.data.priceOpen}`);
+ *   console.log(`Timestamp: ${new Date(event.timestamp).toISOString()}`);
  * });
+ *
+ * // Wait for specific schedule ping
+ * listenSchedulePingOnce(
+ *   (event) => event.symbol === "BTCUSDT",
+ *   (event) => console.log("BTCUSDT schedule ping received:", event.timestamp)
+ * );
  * ```
  */
-interface IFrameSchema {
-    /** Unique identifier for this frame */
-    frameName: FrameName;
-    /** Optional developer note for documentation */
-    note?: string;
-    /** 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 {
+interface SchedulePingContract {
     /**
-     * Generates array of timestamps for backtest iteration.
-     * Timestamps are spaced according to the configured interval.
+     * Trading pair symbol (e.g., "BTCUSDT").
+     * Identifies which market this ping event belongs to.
+     */
+    symbol: string;
+    /**
+     * Strategy name that is monitoring this scheduled signal.
+     * Identifies which strategy execution this ping event belongs to.
+     */
+    strategyName: StrategyName;
+    /**
+     * Exchange name where this scheduled signal is being monitored.
+     * Identifies which exchange this ping event belongs to.
+     */
+    exchangeName: ExchangeName;
+    /**
+     * Complete scheduled signal row data.
+     * Contains all signal information: id, position, priceOpen, priceTakeProfit, priceStopLoss, etc.
+     */
+    data: IScheduledSignalRow;
+    /**
+     * Execution mode flag.
+     * - true: Event from backtest execution (historical candle data)
+     * - false: Event from live trading (real-time tick)
+     */
+    backtest: boolean;
+    /**
+     * Event timestamp in milliseconds since Unix epoch.
      *
-     * @param symbol - Trading pair symbol (unused, for API consistency)
-     * @returns Promise resolving to array of Date objects
+     * Timing semantics:
+     * - Live mode: when.getTime() at the moment of ping
+     * - Backtest mode: candle.timestamp of the candle being processed
+     *
+     * @example
+     * ```typescript
+     * const eventDate = new Date(event.timestamp);
+     * console.log(`Ping at: ${eventDate.toISOString()}`);
+     * ```
      */
-    getTimeframe: (symbol: string, frameName: FrameName) => Promise<Date[]>;
+    timestamp: number;
 }
-/**
- * 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.
+ * Contract for active ping events during active pending signal monitoring.
  *
- * 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.
+ * Emitted by activePingSubject every minute when an active pending signal is being monitored.
+ * Used for tracking active signal lifecycle and custom dynamic management logic.
  *
- * Uses di-scoped for implicit context passing without explicit parameters.
- * Context includes strategyName, exchangeName, and frameName.
+ * Events are emitted only when pending signal is active (not closed yet).
+ * Allows users to implement custom management logic via onActivePing callback.
  *
- * Used by PublicServices to inject schema names into ConnectionServices.
+ * Consumers:
+ * - User callbacks via listenActivePing() / listenActivePingOnce()
  *
  * @example
  * ```typescript
- * MethodContextService.runAsyncIterator(
- *   backtestGenerator,
- *   {
- *     strategyName: "my-strategy",
- *     exchangeName: "my-exchange",
- *     frameName: "1d-backtest"
- *   }
+ * import { listenActivePing } from "backtest-kit";
+ *
+ * // Listen to all active ping events
+ * listenActivePing((event) => {
+ *   console.log(`[${event.backtest ? "Backtest" : "Live"}] Active Ping for ${event.symbol}`);
+ *   console.log(`Strategy: ${event.strategyName}, Exchange: ${event.exchangeName}`);
+ *   console.log(`Signal ID: ${event.data.id}, Position: ${event.data.position}`);
+ *   console.log(`Timestamp: ${new Date(event.timestamp).toISOString()}`);
+ * });
+ *
+ * // Wait for specific active ping
+ * listenActivePingOnce(
+ *   (event) => event.symbol === "BTCUSDT",
+ *   (event) => console.log("BTCUSDT active ping received:", event.timestamp)
  * );
  * ```
  */
-declare const MethodContextService: (new () => {
-    readonly context: IMethodContext;
-}) & Omit<{
-    new (context: IMethodContext): {
-        readonly context: IMethodContext;
-    };
-}, "prototype"> & di_scoped.IScopedClassRun<[context: IMethodContext]>;
-
-/**
- * Risk rejection result type.
- * Can be void, null, or an IRiskRejectionResult object.
- */
-type RiskRejection = void | IRiskRejectionResult | string | null;
-/**
- * Risk check arguments for evaluating whether to allow opening a new position.
- * Called BEFORE signal creation to validate if conditions allow new signals.
- * Contains only passthrough arguments from ClientStrategy context.
- */
-interface IRiskCheckArgs {
-    /** Trading pair symbol (e.g., "BTCUSDT") */
-    symbol: string;
-    /** Pending signal to apply */
-    currentSignal: IPublicSignalRow;
-    /** Strategy name requesting to open a position */
-    strategyName: StrategyName;
-    /** Exchange name */
-    exchangeName: ExchangeName;
-    /** Risk name */
-    riskName: RiskName;
-    /** Frame name */
-    frameName: FrameName;
-    /** Current VWAP price */
-    currentPrice: number;
-    /** Current timestamp */
-    timestamp: number;
-}
-/**
- * Active position tracked by ClientRisk for cross-strategy analysis.
- */
-interface IRiskActivePosition {
-    /** Strategy name owning the position */
-    strategyName: StrategyName;
-    /** Exchange name */
-    exchangeName: ExchangeName;
-    /** Frame name */
-    frameName: FrameName;
-    /** Trading pair symbol (e.g., "BTCUSDT") */
+interface ActivePingContract {
+    /**
+     * Trading pair symbol (e.g., "BTCUSDT").
+     * Identifies which market this ping event belongs to.
+     */
     symbol: string;
-    /** Position direction ("long" or "short") */
-    position: "long" | "short";
-    /** Entry price */
-    priceOpen: number;
-    /** Stop loss price */
-    priceStopLoss: number;
-    /** Take profit price */
-    priceTakeProfit: number;
-    /** Estimated time in minutes */
-    minuteEstimatedTime: number;
-    /** Timestamp when the position was opened */
-    openTimestamp: number;
-}
-/**
- * Optional callbacks for risk events.
- */
-interface IRiskCallbacks {
-    /** Called when a signal is rejected due to risk limits */
-    onRejected: (symbol: string, params: IRiskCheckArgs) => void | Promise<void>;
-    /** Called when a signal passes risk checks */
-    onAllowed: (symbol: string, params: IRiskCheckArgs) => void | Promise<void>;
-}
-/**
- * Payload passed to risk validation functions.
- * Extends IRiskCheckArgs with portfolio state data.
- */
-interface IRiskValidationPayload extends IRiskCheckArgs {
-    /** Current signal being validated (IRiskSignalRow is calculated internally so priceOpen always exist) */
-    currentSignal: IRiskSignalRow;
-    /** Number of currently active positions across all strategies */
-    activePositionCount: number;
-    /** List of currently active positions across all strategies */
-    activePositions: IRiskActivePosition[];
-}
-/**
- * Risk validation rejection result.
- * Returned when validation fails, contains debugging information.
- */
-interface IRiskRejectionResult {
-    /** Unique identifier for this rejection instance */
-    id: string | null;
-    /** Human-readable reason for rejection */
-    note: string;
-}
-/**
- * Risk validation function type.
- * Returns null/void if validation passes, IRiskRejectionResult if validation fails.
- * Can also throw error which will be caught and converted to IRiskRejectionResult.
- */
-interface IRiskValidationFn {
-    (payload: IRiskValidationPayload): RiskRejection | Promise<RiskRejection>;
-}
-/**
- * Risk validation configuration.
- * Defines validation logic with optional documentation.
- */
-interface IRiskValidation {
     /**
-     * The validation function to apply to the risk check parameters.
+     * Strategy name that is monitoring this active pending signal.
+     * Identifies which strategy execution this ping event belongs to.
      */
-    validate: IRiskValidationFn;
+    strategyName: StrategyName;
     /**
-     * Optional description for documentation purposes.
-     * Aids in understanding the purpose or behavior of the validation.
+     * Exchange name where this active pending signal is being monitored.
+     * Identifies which exchange this ping event belongs to.
      */
-    note?: string;
-}
-/**
- * Risk schema registered via addRisk().
- * Defines portfolio-level risk controls via custom validations.
- */
-interface IRiskSchema {
-    /** Unique risk profile identifier */
-    riskName: RiskName;
-    /** Optional developer note for documentation */
-    note?: string;
-    /** Optional lifecycle event callbacks (onRejected, onAllowed) */
-    callbacks?: Partial<IRiskCallbacks>;
-    /** Custom validations array for risk logic */
-    validations: (IRiskValidation | IRiskValidationFn)[];
-}
-/**
- * Risk parameters passed to ClientRisk constructor.
- * Combines schema with runtime dependencies and emission callbacks.
- */
-interface IRiskParams extends IRiskSchema {
-    /** Exchange name (e.g., "binance") */
     exchangeName: ExchangeName;
-    /** Logger service for debug output */
-    logger: ILogger;
-    /** True if backtest mode, false if live mode */
-    backtest: boolean;
     /**
-     * Callback invoked when a signal is rejected due to risk limits.
-     * Called before emitting to riskSubject.
-     * Used for event emission to riskSubject (separate from schema callbacks).
-     *
-     * @param symbol - Trading pair symbol
-     * @param params - Risk check arguments
-     * @param activePositionCount - Number of active positions at rejection time
-     * @param rejectionResult - Rejection result with id and note
-     * @param timestamp - Event timestamp in milliseconds
-     * @param backtest - True if backtest mode, false if live mode
+     * Complete pending signal row data.
+     * Contains all signal information: id, position, priceOpen, priceTakeProfit, priceStopLoss, etc.
      */
-    onRejected: (symbol: string, params: IRiskCheckArgs, activePositionCount: number, rejectionResult: IRiskRejectionResult, timestamp: number, backtest: boolean) => void | Promise<void>;
-}
-/**
- * Risk interface implemented by ClientRisk.
- * Provides risk checking for signals and position tracking.
- */
-interface IRisk {
+    data: ISignalRow;
     /**
-     * Check if a signal should be allowed based on risk limits.
-     *
-     * @param params - Risk check arguments (position size, portfolio state, etc.)
-     * @returns Promise resolving to risk check result
+     * Execution mode flag.
+     * - true: Event from backtest execution (historical candle data)
+     * - false: Event from live trading (real-time tick)
      */
-    checkSignal: (params: IRiskCheckArgs) => Promise<boolean>;
+    backtest: boolean;
     /**
-     * Register a new opened signal/position.
+     * Event timestamp in milliseconds since Unix epoch.
      *
-     * @param symbol - Trading pair symbol
-     * @param context - Context information (strategyName, riskName, exchangeName, frameName)
-     * @param positionData - Position data (position, prices, timing)
-     */
-    addSignal: (symbol: string, context: {
-        strategyName: StrategyName;
-        riskName: RiskName;
-        exchangeName: ExchangeName;
-        frameName: FrameName;
-    }, positionData: {
-        position: "long" | "short";
-        priceOpen: number;
-        priceStopLoss: number;
-        priceTakeProfit: number;
-        minuteEstimatedTime: number;
-        openTimestamp: number;
-    }) => Promise<void>;
-    /**
-     * Remove a closed signal/position.
+     * Timing semantics:
+     * - Live mode: when.getTime() at the moment of ping
+     * - Backtest mode: candle.timestamp of the candle being processed
      *
-     * @param symbol - Trading pair symbol
-     * @param context - Context information (strategyName, riskName, exchangeName, frameName)
+     * @example
+     * ```typescript
+     * const eventDate = new Date(event.timestamp);
+     * console.log(`Active Ping at: ${eventDate.toISOString()}`);
+     * ```
      */
-    removeSignal: (symbol: string, context: {
-        strategyName: StrategyName;
-        riskName: RiskName;
-        exchangeName: ExchangeName;
-        frameName: FrameName;
-    }) => Promise<void>;
+    timestamp: number;
 }
-/**
- * Unique risk profile identifier.
- */
-type RiskName = string;
 
 /**
- * Profit or loss level milestone in percentage points.
- * Represents 10%, 20%, 30%, ..., 100% profit or loss thresholds.
+ * Contract for risk rejection events.
  *
- * Used to track when a signal reaches specific profit/loss milestones.
- * Each level is emitted only once per signal (deduplication via Set).
+ * Emitted by riskSubject ONLY when a signal is REJECTED due to risk validation failure.
+ * Used for tracking actual risk violations and monitoring rejected signals.
+ *
+ * Events are emitted only when risk limits are violated (not for allowed signals).
+ * This prevents spam and allows focusing on actual risk management interventions.
+ *
+ * Consumers:
+ * - RiskMarkdownService: Accumulates rejection events for report generation
+ * - User callbacks via listenRisk() / listenRiskOnce()
  *
  * @example
  * ```typescript
- * const level: PartialLevel = 50; // 50% profit or loss milestone
- * ```
- */
-type PartialLevel = 10 | 20 | 30 | 40 | 50 | 60 | 70 | 80 | 90 | 100;
-/**
- * Serializable partial data for persistence layer.
- * Converts Sets to arrays for JSON serialization.
+ * import { listenRisk } from "backtest-kit";
  *
- * Stored in PersistPartialAdapter as Record<signalId, IPartialData>.
- * Loaded on initialization and converted back to IPartialState.
+ * // Listen to all risk rejection events
+ * listenRisk((event) => {
+ *   console.log(`[RISK REJECTED] Signal for ${event.symbol}`);
+ *   console.log(`Strategy: ${event.strategyName}`);
+ *   console.log(`Active positions: ${event.activePositionCount}`);
+ *   console.log(`Price: ${event.currentPrice}`);
+ *   console.log(`Timestamp: ${new Date(event.timestamp).toISOString()}`);
+ * });
+ *
+ * // Alert on risk rejections for specific symbol
+ * listenRisk((event) => {
+ *   if (event.symbol === "BTCUSDT") {
+ *     console.warn("BTC signal rejected due to risk limits!");
+ *   }
+ * });
+ * ```
  */
-interface IPartialData {
+interface RiskContract {
     /**
-     * Array of profit levels that have been reached for this signal.
-     * Serialized form of IPartialState.profitLevels Set.
+     * Trading pair symbol (e.g., "BTCUSDT").
+     * Identifies which market this rejected signal belongs to.
      */
-    profitLevels: PartialLevel[];
+    symbol: string;
     /**
-     * Array of loss levels that have been reached for this signal.
-     * Serialized form of IPartialState.lossLevels Set.
+     * Pending signal to apply.
+     * Contains signal details (position, priceOpen, priceTakeProfit, priceStopLoss, etc).
      */
-    lossLevels: PartialLevel[];
-}
-/**
- * Partial profit/loss tracking interface.
- * Implemented by ClientPartial and PartialConnectionService.
- *
- * Tracks profit/loss level milestones for active trading signals.
- * Emits events when signals reach 10%, 20%, 30%, etc profit or loss.
- *
- * @example
- * ```typescript
- * import { ClientPartial } from "./client/ClientPartial";
- *
- * const partial = new ClientPartial({
- *   logger: loggerService,
- *   onProfit: (symbol, data, price, level, backtest, timestamp) => {
- *     console.log(`Signal ${data.id} reached ${level}% profit`);
- *   },
- *   onLoss: (symbol, data, price, level, backtest, timestamp) => {
- *     console.log(`Signal ${data.id} reached ${level}% loss`);
- *   }
- * });
- *
- * await partial.waitForInit("BTCUSDT");
- *
- * // During signal monitoring
- * await partial.profit("BTCUSDT", signal, 51000, 15.5, false, new Date());
- * // Emits event when reaching 10% profit milestone
- *
- * // When signal closes
- * await partial.clear("BTCUSDT", signal, 52000);
- * ```
- */
-interface IPartial {
+    currentSignal: ISignalDto;
     /**
-     * Processes profit state and emits events for new profit levels reached.
-     *
-     * Called by ClientStrategy during signal monitoring when revenuePercent > 0.
-     * Checks which profit levels (10%, 20%, 30%, etc) have been reached
-     * and emits events for new levels only (Set-based deduplication).
-     *
-     * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
-     * @param data - Signal row data
-     * @param currentPrice - Current market price
-     * @param revenuePercent - Current profit percentage (positive value)
-     * @param backtest - True if backtest mode, false if live mode
-     * @param when - Event timestamp (current time for live, candle time for backtest)
-     * @returns Promise that resolves when profit processing is complete
-     *
-     * @example
-     * ```typescript
-     * // Signal opened at $50000, current price $51500
-     * // Revenue: 3% profit
-     * await partial.profit("BTCUSDT", signal, 51500, 3.0, false, new Date());
-     * // No events emitted (below 10% threshold)
-     *
-     * // Price rises to $55000
-     * // Revenue: 10% profit
-     * await partial.profit("BTCUSDT", signal, 55000, 10.0, false, new Date());
-     * // Emits partialProfitSubject event for 10% level
-     *
-     * // Price rises to $61000
-     * // Revenue: 22% profit
-     * await partial.profit("BTCUSDT", signal, 61000, 22.0, false, new Date());
-     * // Emits events for 20% level only (10% already emitted)
-     * ```
+     * Strategy name requesting to open a position.
+     * Identifies which strategy attempted to create the signal.
      */
-    profit(symbol: string, data: IPublicSignalRow, currentPrice: number, revenuePercent: number, backtest: boolean, when: Date): Promise<void>;
+    strategyName: StrategyName;
     /**
-     * Processes loss state and emits events for new loss levels reached.
-     *
-     * Called by ClientStrategy during signal monitoring when revenuePercent < 0.
-     * Checks which loss levels (10%, 20%, 30%, etc) have been reached
-     * and emits events for new levels only (Set-based deduplication).
-     *
-     * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
-     * @param data - Signal row data
-     * @param currentPrice - Current market price
-     * @param lossPercent - Current loss percentage (negative value)
-     * @param backtest - True if backtest mode, false if live mode
-     * @param when - Event timestamp (current time for live, candle time for backtest)
-     * @returns Promise that resolves when loss processing is complete
+     * Frame name used in backtest execution.
+     * Identifies which frame this signal was for in backtest execution.
+     */
+    frameName: FrameName;
+    /**
+     * Exchange name.
+     * Identifies which exchange this signal was for.
+     */
+    exchangeName: ExchangeName;
+    /**
+     * Current VWAP price at the time of rejection.
+     * Market price when risk check was performed.
+     */
+    currentPrice: number;
+    /**
+     * Number of currently active positions across all strategies at rejection time.
+     * Used to track portfolio-level exposure when signal was rejected.
+     */
+    activePositionCount: number;
+    /**
+     * Unique identifier for this rejection instance.
+     * Generated by ClientRisk for tracking and debugging purposes.
+     * Null if validation threw exception without custom ID.
+     */
+    rejectionId: string | null;
+    /**
+     * Human-readable reason why the signal was rejected.
+     * Captured from IRiskValidation.note or error message.
      *
      * @example
      * ```typescript
-     * // Signal opened at $50000, current price $48000
-     * // Loss: -4% loss
-     * await partial.loss("BTCUSDT", signal, 48000, -4.0, false, new Date());
-     * // No events emitted (below -10% threshold)
-     *
-     * // Price drops to $45000
-     * // Loss: -10% loss
-     * await partial.loss("BTCUSDT", signal, 45000, -10.0, false, new Date());
-     * // Emits partialLossSubject event for 10% level
-     *
-     * // Price drops to $39000
-     * // Loss: -22% loss
-     * await partial.loss("BTCUSDT", signal, 39000, -22.0, false, new Date());
-     * // Emits events for 20% level only (10% already emitted)
+     * console.log(`Rejection reason: ${event.rejectionNote}`);
+     * // Output: "Rejection reason: Max 3 positions allowed"
      * ```
      */
-    loss(symbol: string, data: IPublicSignalRow, currentPrice: number, lossPercent: number, backtest: boolean, when: Date): Promise<void>;
+    rejectionNote: string;
     /**
-     * Clears partial profit/loss state when signal closes.
-     *
-     * Called by ClientStrategy when signal completes (TP/SL/time_expired).
-     * Removes signal state from memory and persists changes to disk.
-     * Cleans up memoized ClientPartial instance in PartialConnectionService.
-     *
-     * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
-     * @param data - Signal row data
-     * @param priceClose - Final closing price
-     * @returns Promise that resolves when clear is complete
+     * Event timestamp in milliseconds since Unix epoch.
+     * Represents when the signal was rejected.
      *
      * @example
      * ```typescript
-     * // Signal closes at take profit
-     * await partial.clear("BTCUSDT", signal, 52000);
-     * // State removed from _states Map
-     * // Persisted to disk without this signal's data
-     * // Memoized instance cleared from getPartial cache
+     * const eventDate = new Date(event.timestamp);
+     * console.log(`Signal rejected at: ${eventDate.toISOString()}`);
      * ```
      */
-    clear(symbol: string, data: IPublicSignalRow, priceClose: number, backtest: boolean): Promise<void>;
+    timestamp: number;
+    /**
+     * Whether this event is from backtest mode (true) or live mode (false).
+     * Used to separate backtest and live risk rejection tracking.
+     */
+    backtest: boolean;
 }
 
 /**
- * Serializable breakeven data for persistence layer.
- * Converts state to simple boolean for JSON serialization.
+ * Constructor type for action handlers with strategy context.
  *
- * Stored in PersistBreakevenAdapter as Record<signalId, IBreakevenData>.
- * Loaded on initialization and converted back to IBreakevenState.
+ * @param strategyName - Strategy identifier (e.g., "rsi_divergence", "macd_cross")
+ * @param frameName - Timeframe identifier (e.g., "1m", "5m", "1h")
+ * @param backtest - True for backtest mode, false for live trading
+ * @returns Partial implementation of IAction (only required handlers)
+ *
+ * @example
+ * ```typescript
+ * class TelegramNotifier implements Partial<IAction> {
+ *   constructor(
+ *     private strategyName: StrategyName,
+ *     private frameName: FrameName,
+ *     private backtest: boolean
+ *   ) {}
+ *
+ *   signal(event: IStrategyTickResult): void {
+ *     if (!this.backtest && event.state === 'opened') {
+ *       telegram.send(`[${this.strategyName}/${this.frameName}] New signal`);
+ *     }
+ *   }
+ * }
+ *
+ * const actionCtors: TActionCtor[] = [TelegramNotifier, ReduxLogger];
+ * ```
  */
-interface IBreakevenData {
-    /**
-     * Whether breakeven has been reached for this signal.
-     * Serialized form of IBreakevenState.reached.
-     */
-    reached: boolean;
-}
+type TActionCtor = new (strategyName: StrategyName, frameName: FrameName, actionName: ActionName, backtest: boolean) => Partial<IPublicAction>;
 /**
- * Breakeven tracking interface.
- * Implemented by ClientBreakeven and BreakevenConnectionService.
+ * Action parameters passed to ClientAction constructor.
+ * Combines schema with runtime dependencies and execution context.
  *
- * Tracks when a signal's stop-loss is moved to breakeven (entry price).
- * Emits events when threshold is reached (price moves far enough to cover transaction costs).
+ * Extended from IActionSchema with:
+ * - Logger instance for debugging and monitoring
+ * - Strategy context (strategyName, frameName)
+ * - Runtime environment flags
  *
  * @example
  * ```typescript
- * import { ClientBreakeven } from "./client/ClientBreakeven";
- *
- * const breakeven = new ClientBreakeven({
+ * const params: IActionParams = {
+ *   actionName: "telegram-notifier",
+ *   handler: TelegramNotifier,
+ *   callbacks: { onInit, onDispose, onSignal },
  *   logger: loggerService,
- *   onBreakeven: (symbol, data, price, backtest, timestamp) => {
- *     console.log(`Signal ${data.id} reached breakeven at ${price}`);
- *   }
- * });
+ *   strategyName: "rsi_divergence",
+ *   frameName: "1h"
+ * };
  *
- * await breakeven.waitForInit("BTCUSDT");
+ * const actionClient = new ClientAction(params);
+ * ```
+ */
+interface IActionParams extends IActionSchema {
+    /** Logger service for debugging and monitoring action execution */
+    logger: ILogger;
+    /** Strategy identifier this action is attached to */
+    strategyName: StrategyName;
+    /** Exchange name (e.g., "binance") */
+    exchangeName: ExchangeName;
+    /** Timeframe identifier this action is attached to */
+    frameName: FrameName;
+    /** Whether running in backtest mode */
+    backtest: boolean;
+}
+/**
+ * Lifecycle and event callbacks for action handlers.
  *
- * // During signal monitoring
- * await breakeven.check("BTCUSDT", signal, 100.5, false, new Date());
- * // Emits event when threshold reached and SL moved to entry
+ * Provides hooks for initialization, disposal, and event handling.
+ * All callbacks are optional and support both sync and async execution.
  *
- * // When signal closes
- * await breakeven.clear("BTCUSDT", signal, 101, false);
+ * Use cases:
+ * - Resource initialization (database connections, file handles)
+ * - Resource cleanup (close connections, flush buffers)
+ * - Event logging and monitoring
+ * - State persistence
+ *
+ * @example
+ * ```typescript
+ * const callbacks: IActionCallbacks = {
+ *   onInit: async (strategyName, frameName, backtest) => {
+ *     console.log(`[${strategyName}/${frameName}] Action initialized (backtest=${backtest})`);
+ *     await db.connect();
+ *   },
+ *   onSignal: (event, strategyName, frameName, backtest) => {
+ *     if (event.action === 'opened') {
+ *       console.log(`New signal opened: ${event.signal.id}`);
+ *     }
+ *   },
+ *   onDispose: async (strategyName, frameName, backtest) => {
+ *     await db.disconnect();
+ *     console.log(`[${strategyName}/${frameName}] Action disposed`);
+ *   }
+ * };
  * ```
  */
-interface IBreakeven {
+interface IActionCallbacks {
     /**
-     * Checks if breakeven should be triggered and emits event if conditions met.
+     * Called when action handler is initialized.
      *
-     * Called by ClientStrategy during signal monitoring.
-     * Checks if:
-     * 1. Breakeven not already reached
-     * 2. Price has moved far enough to cover transaction costs
-     * 3. Stop-loss can be moved to entry price
-     *
-     * If all conditions met:
-     * - Marks breakeven as reached
-     * - Calls onBreakeven callback (emits to breakevenSubject)
-     * - Persists state to disk
-     *
-     * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
-     * @param data - Signal row data
-     * @param currentPrice - Current market price
-     * @param backtest - True if backtest mode, false if live mode
-     * @param when - Event timestamp (current time for live, candle time for backtest)
-     * @returns Promise that resolves when breakeven check is complete
+     * Use for:
+     * - Opening database connections
+     * - Initializing external services
+     * - Loading persisted state
+     * - Setting up subscriptions
      *
-     * @example
-     * ```typescript
-     * // LONG: entry=100, slippage=0.1%, fee=0.1%, threshold=0.4%
-     * // Price at 100.3 - threshold not reached
-     * await breakeven.check("BTCUSDT", signal, 100.3, false, new Date());
-     * // No event emitted (price < 100.4)
+     * @param actionName - Action identifier
+     * @param strategyName - Strategy identifier
+     * @param frameName - Timeframe identifier
+     * @param backtest - True for backtest mode, false for live trading
+     */
+    onInit(actionName: ActionName, strategyName: StrategyName, frameName: FrameName, backtest: boolean): void | Promise<void>;
+    /**
+     * Called when action handler is disposed.
      *
-     * // Price at 100.5 - threshold reached!
-     * await breakeven.check("BTCUSDT", signal, 100.5, false, new Date());
-     * // Emits breakevenSubject event
+     * Use for:
+     * - Closing database connections
+     * - Flushing buffers
+     * - Saving state to disk
+     * - Unsubscribing from observables
      *
-     * // Price at 101 - already at breakeven
-     * await breakeven.check("BTCUSDT", signal, 101, false, new Date());
-     * // No event emitted (already reached)
-     * ```
+     * @param actionName - Action identifier
+     * @param strategyName - Strategy identifier
+     * @param frameName - Timeframe identifier
+     * @param backtest - True for backtest mode, false for live trading
      */
-    check(symbol: string, data: IPublicSignalRow, currentPrice: number, backtest: boolean, when: Date): Promise<boolean>;
+    onDispose(actionName: ActionName, strategyName: StrategyName, frameName: FrameName, backtest: boolean): void | Promise<void>;
     /**
-     * Clears breakeven state when signal closes.
-     *
-     * Called by ClientStrategy when signal completes (TP/SL/time_expired).
-     * Removes signal state from memory and persists changes to disk.
-     * Cleans up memoized ClientBreakeven instance in BreakevenConnectionService.
+     * Called on signal events from all modes (live + backtest).
      *
-     * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
-     * @param data - Signal row data
-     * @param priceClose - Final closing price
-     * @param backtest - True if backtest mode, false if live mode
-     * @returns Promise that resolves when clear is complete
+     * Triggered by: StrategyConnectionService via signalEmitter
+     * Frequency: Every tick/candle when strategy is evaluated
      *
-     * @example
-     * ```typescript
-     * // Signal closes at take profit
-     * await breakeven.clear("BTCUSDT", signal, 101);
-     * // State removed from _states Map
-     * // Persisted to disk without this signal's data
-     * // Memoized instance cleared from getBreakeven cache
-     * ```
+     * @param event - Signal state result (idle, scheduled, opened, active, closed, cancelled)
+     * @param actionName - Action identifier
+     * @param strategyName - Strategy identifier
+     * @param frameName - Timeframe identifier
+     * @param backtest - True for backtest mode, false for live trading
      */
-    clear(symbol: string, data: IPublicSignalRow, priceClose: number, backtest: boolean): Promise<void>;
-}
-
-/**
- * Contract for breakeven events.
- *
- * Emitted by breakevenSubject when a signal's stop-loss is moved to breakeven (entry price).
- * Used for tracking risk reduction milestones and monitoring strategy safety.
- *
- * Events are emitted only once per signal (idempotent - protected by ClientBreakeven state).
- * Breakeven is triggered when price moves far enough in profit direction to cover transaction costs.
- *
- * Consumers:
- * - BreakevenMarkdownService: Accumulates events for report generation
- * - User callbacks via listenBreakeven() / listenBreakevenOnce()
- *
- * @example
- * ```typescript
- * import { listenBreakeven } from "backtest-kit";
- *
- * // Listen to all breakeven events
- * listenBreakeven((event) => {
- *   console.log(`[${event.backtest ? "Backtest" : "Live"}] Signal ${event.data.id} moved to breakeven`);
- *   console.log(`Symbol: ${event.symbol}, Price: ${event.currentPrice}`);
- *   console.log(`Position: ${event.data.position}, Entry: ${event.data.priceOpen}`);
- *   console.log(`Original SL: ${event.data.priceStopLoss}, New SL: ${event.data.priceOpen}`);
- * });
- *
- * // Wait for specific signal to reach breakeven
- * listenBreakevenOnce(
- *   (event) => event.data.id === "target-signal-id",
- *   (event) => console.log("Signal reached breakeven:", event.data.id)
- * );
- * ```
- */
-interface BreakevenContract {
+    onSignal(event: IStrategyTickResult, actionName: ActionName, strategyName: StrategyName, frameName: FrameName, backtest: boolean): void | Promise<void>;
     /**
-     * Trading pair symbol (e.g., "BTCUSDT").
-     * Identifies which market this breakeven event belongs to.
+     * Called on signal events from live trading only.
+     *
+     * Triggered by: StrategyConnectionService via signalLiveEmitter
+     * Frequency: Every tick in live mode
+     *
+     * @param event - Signal state result from live trading
+     * @param actionName - Action identifier
+     * @param strategyName - Strategy identifier
+     * @param frameName - Timeframe identifier
+     * @param backtest - Always false (live mode only)
      */
-    symbol: string;
+    onSignalLive(event: IStrategyTickResult, actionName: ActionName, strategyName: StrategyName, frameName: FrameName, backtest: boolean): void | Promise<void>;
     /**
-     * Strategy name that generated this signal.
-     * Identifies which strategy execution this breakeven event belongs to.
+     * Called on signal events from backtest only.
+     *
+     * Triggered by: StrategyConnectionService via signalBacktestEmitter
+     * Frequency: Every candle in backtest mode
+     *
+     * @param event - Signal state result from backtest
+     * @param actionName - Action identifier
+     * @param strategyName - Strategy identifier
+     * @param frameName - Timeframe identifier
+     * @param backtest - Always true (backtest mode only)
      */
-    strategyName: StrategyName;
+    onSignalBacktest(event: IStrategyTickResult, actionName: ActionName, strategyName: StrategyName, frameName: FrameName, backtest: boolean): void | Promise<void>;
     /**
-     * Exchange name where this signal is being executed.
-     * Identifies which exchange this breakeven event belongs to.
+     * Called when breakeven is triggered (stop-loss moved to entry price).
+     *
+     * Triggered by: BreakevenConnectionService via breakevenSubject
+     * Frequency: Once per signal when breakeven threshold is reached
+     *
+     * @param event - Breakeven milestone data
+     * @param actionName - Action identifier
+     * @param strategyName - Strategy identifier
+     * @param frameName - Timeframe identifier
+     * @param backtest - True for backtest mode, false for live trading
      */
-    exchangeName: ExchangeName;
+    onBreakevenAvailable(event: BreakevenContract, actionName: ActionName, strategyName: StrategyName, frameName: FrameName, backtest: boolean): void | Promise<void>;
     /**
-     * Frame name where this signal is being executed.
-     * Identifies which frame this breakeven event belongs to (empty string for live mode).
+     * Called when partial profit level is reached (10%, 20%, 30%, etc).
+     *
+     * Triggered by: PartialConnectionService via partialProfitSubject
+     * Frequency: Once per profit level per signal (deduplicated)
+     *
+     * @param event - Profit milestone data with level and price
+     * @param actionName - Action identifier
+     * @param strategyName - Strategy identifier
+     * @param frameName - Timeframe identifier
+     * @param backtest - True for backtest mode, false for live trading
      */
-    frameName: FrameName;
+    onPartialProfitAvailable(event: PartialProfitContract, actionName: ActionName, strategyName: StrategyName, frameName: FrameName, backtest: boolean): void | Promise<void>;
     /**
-     * Complete signal row data with original prices.
-     * Contains all signal information including originalPriceStopLoss, originalPriceTakeProfit, and partialExecuted.
+     * Called when partial loss level is reached (-10%, -20%, -30%, etc).
+     *
+     * Triggered by: PartialConnectionService via partialLossSubject
+     * Frequency: Once per loss level per signal (deduplicated)
+     *
+     * @param event - Loss milestone data with level and price
+     * @param actionName - Action identifier
+     * @param strategyName - Strategy identifier
+     * @param frameName - Timeframe identifier
+     * @param backtest - True for backtest mode, false for live trading
      */
-    data: IPublicSignalRow;
+    onPartialLossAvailable(event: PartialLossContract, actionName: ActionName, strategyName: StrategyName, frameName: FrameName, backtest: boolean): void | Promise<void>;
     /**
-     * Current market price at which breakeven was triggered.
-     * Used to verify threshold calculation.
+     * Called during scheduled signal monitoring (every minute while waiting for activation).
+     *
+     * Triggered by: StrategyConnectionService via schedulePingSubject
+     * Frequency: Every minute while scheduled signal is waiting
+     *
+     * @param event - Scheduled signal monitoring data
+     * @param actionName - Action identifier
+     * @param strategyName - Strategy identifier
+     * @param frameName - Timeframe identifier
+     * @param backtest - True for backtest mode, false for live trading
      */
-    currentPrice: number;
+    onPingScheduled(event: SchedulePingContract, actionName: ActionName, strategyName: StrategyName, frameName: FrameName, backtest: boolean): void | Promise<void>;
     /**
-     * Execution mode flag.
-     * - true: Event from backtest execution (historical candle data)
-     * - false: Event from live trading (real-time tick)
+     * Called during active pending signal monitoring (every minute while position is active).
+     *
+     * Triggered by: StrategyConnectionService via activePingSubject
+     * Frequency: Every minute while pending signal is active
+     *
+     * @param event - Active pending signal monitoring data
+     * @param actionName - Action identifier
+     * @param strategyName - Strategy identifier
+     * @param frameName - Timeframe identifier
+     * @param backtest - True for backtest mode, false for live trading
      */
-    backtest: boolean;
+    onPingActive(event: ActivePingContract, actionName: ActionName, strategyName: StrategyName, frameName: FrameName, backtest: boolean): void | Promise<void>;
     /**
-     * Event timestamp in milliseconds since Unix epoch.
+     * Called when signal is rejected by risk management.
      *
-     * Timing semantics:
-     * - Live mode: when.getTime() at the moment breakeven was set
-     * - Backtest mode: candle.timestamp of the candle that triggered breakeven
+     * Triggered by: RiskConnectionService via riskSubject
+     * Frequency: Only when signal fails risk validation (not emitted for allowed signals)
      *
-     * @example
-     * ```typescript
-     * const eventDate = new Date(event.timestamp);
-     * console.log(`Breakeven set at: ${eventDate.toISOString()}`);
-     * ```
+     * @param event - Risk rejection data with reason and context
+     * @param actionName - Action identifier
+     * @param strategyName - Strategy identifier
+     * @param frameName - Timeframe identifier
+     * @param backtest - True for backtest mode, false for live trading
      */
-    timestamp: number;
+    onRiskRejection(event: RiskContract, actionName: ActionName, strategyName: StrategyName, frameName: FrameName, backtest: boolean): void | Promise<void>;
 }
-
 /**
- * Contract for partial profit level events.
- *
- * Emitted by partialProfitSubject when a signal reaches a profit level milestone (10%, 20%, 30%, etc).
- * Used for tracking partial take-profit execution and monitoring strategy performance.
+ * Action schema registered via addActionSchema().
+ * Defines event handler implementation and lifecycle callbacks for state management integration.
  *
- * Events are emitted only once per level per signal (Set-based deduplication in ClientPartial).
- * Multiple levels can be emitted in a single tick if price jumps significantly.
+ * Actions provide a way to attach custom event handlers to strategies for:
+ * - State management (Redux, Zustand, MobX)
+ * - Event logging and monitoring
+ * - Real-time notifications (Telegram, Discord, email)
+ * - Analytics and metrics collection
+ * - Custom business logic triggers
  *
- * Consumers:
- * - PartialMarkdownService: Accumulates events for report generation
- * - User callbacks via listenPartialProfit() / listenPartialProfitOnce()
+ * Each action instance is created per strategy-frame pair and receives all events
+ * emitted during strategy execution. Multiple actions can be attached to a single strategy.
  *
  * @example
  * ```typescript
- * import { listenPartialProfit } from "backtest-kit";
+ * import { addActionSchema } from "backtest-kit";
  *
- * // Listen to all partial profit events
- * listenPartialProfit((event) => {
- *   console.log(`[${event.backtest ? "Backtest" : "Live"}] Signal ${event.data.id} reached ${event.level}% profit`);
- *   console.log(`Symbol: ${event.symbol}, Price: ${event.currentPrice}`);
- *   console.log(`Position: ${event.data.position}, Entry: ${event.data.priceOpen}`);
+ * // Define action handler class
+ * class TelegramNotifier implements Partial<IAction> {
+ *   constructor(
+ *     private strategyName: StrategyName,
+ *     private frameName: FrameName,
+ *     private backtest: boolean
+ *   ) {}
+ *
+ *   signal(event: IStrategyTickResult): void {
+ *     if (!this.backtest && event.action === 'opened') {
+ *       telegram.send(`[${this.strategyName}/${this.frameName}] New signal`);
+ *     }
+ *   }
+ *
+ *   dispose(): void {
+ *     telegram.close();
+ *   }
+ * }
+ *
+ * // Register action schema
+ * addActionSchema({
+ *   actionName: "telegram-notifier",
+ *   handler: TelegramNotifier,
+ *   callbacks: {
+ *     onInit: async (strategyName, frameName, backtest) => {
+ *       console.log(`Telegram notifier initialized for ${strategyName}/${frameName}`);
+ *     },
+ *     onSignal: (event, strategyName, frameName, backtest) => {
+ *       console.log(`Signal event: ${event.action}`);
+ *     }
+ *   }
  * });
+ * ```
+ */
+interface IActionSchema {
+    /** Unique action identifier for registration */
+    actionName: ActionName;
+    /** Optional developer note for documentation */
+    note?: string;
+    /** Action handler constructor (instantiated per strategy-frame pair) */
+    handler: TActionCtor | Partial<IPublicAction>;
+    /** Optional lifecycle and event callbacks */
+    callbacks?: Partial<IActionCallbacks>;
+}
+/**
+ * Public action interface for custom action handler implementations.
  *
- * // Wait for first 50% profit level
- * listenPartialProfitOnce(
- *   (event) => event.level === 50,
- *   (event) => console.log("50% profit reached:", event.data.id)
- * );
+ * Extends IAction with an initialization lifecycle method.
+ * Action handlers implement this interface to receive strategy events and perform custom logic.
+ *
+ * Lifecycle:
+ * 1. Constructor called with (strategyName, frameName, actionName)
+ * 2. init() called once for async initialization (setup connections, load resources)
+ * 3. Event methods called as strategy executes (signal, breakeven, partialProfit, etc.)
+ * 4. dispose() called once for cleanup (close connections, flush buffers)
+ *
+ * Key features:
+ * - init() for async initialization (database connections, API clients, file handles)
+ * - All IAction methods available for event handling
+ * - dispose() guaranteed to run exactly once via singleshot pattern
+ *
+ * Common use cases:
+ * - State management: Redux/Zustand store integration
+ * - Notifications: Telegram/Discord/Email alerts
+ * - Logging: Custom event tracking and monitoring
+ * - Analytics: Metrics collection and reporting
+ * - External systems: Database writes, API calls, file operations
+ *
+ * @example
+ * ```typescript
+ * class TelegramNotifier implements Partial<IPublicAction> {
+ *   private bot: TelegramBot | null = null;
+ *
+ *   constructor(
+ *     private strategyName: string,
+ *     private frameName: string,
+ *     private actionName: string
+ *   ) {}
+ *
+ *   // Called once during initialization
+ *   async init() {
+ *     this.bot = new TelegramBot(process.env.TELEGRAM_TOKEN);
+ *     await this.bot.connect();
+ *   }
+ *
+ *   // Called on every signal event
+ *   async signal(event: IStrategyTickResult) {
+ *     if (event.action === 'opened') {
+ *       await this.bot.send(
+ *         `[${this.strategyName}/${this.frameName}] Signal opened: ${event.signal.side}`
+ *       );
+ *     }
+ *   }
+ *
+ *   // Called once during cleanup
+ *   async dispose() {
+ *     await this.bot?.disconnect();
+ *     this.bot = null;
+ *   }
+ * }
  * ```
+ *
+ * @see IAction for all available event methods
+ * @see TActionCtor for constructor signature requirements
+ * @see ClientAction for internal wrapper that manages lifecycle
  */
-interface PartialProfitContract {
+type IPublicAction = {
+    [key in keyof IAction]?: IAction[key];
+} & {
+    init?(): void | Promise<void>;
+};
+/**
+ * Action interface for state manager integration.
+ *
+ * Provides methods to handle all events emitted by connection services.
+ * Each method corresponds to a specific event type emitted via .next() calls.
+ *
+ * Use this interface to implement custom state management logic:
+ * - Redux/Zustand action dispatchers
+ * - Event logging systems
+ * - Real-time monitoring dashboards
+ * - Analytics and metrics collection
+ *
+ * @example
+ * ```typescript
+ * class ReduxStateManager implements IAction {
+ *   constructor(private store: Store) {}
+ *
+ *   signal(event: IStrategyTickResult): void {
+ *     this.store.dispatch({ type: 'SIGNAL', payload: event });
+ *   }
+ *
+ *   breakeven(event: BreakevenContract): void {
+ *     this.store.dispatch({ type: 'BREAKEVEN', payload: event });
+ *   }
+ *
+ *   // ... implement other methods
+ * }
+ * ```
+ */
+interface IAction {
     /**
-     * Trading pair symbol (e.g., "BTCUSDT").
-     * Identifies which market this profit event belongs to.
+     * Handles signal events from all modes (live + backtest).
+     *
+     * Emitted by: StrategyConnectionService via signalEmitter
+     * Source: StrategyConnectionService.tick() and StrategyConnectionService.backtest()
+     * Frequency: Every tick/candle when strategy is evaluated
+     *
+     * @param event - Signal state result (idle, scheduled, opened, active, closed, cancelled)
      */
-    symbol: string;
+    signal(event: IStrategyTickResult): void | Promise<void>;
     /**
-     * Strategy name that generated this signal.
-     * Identifies which strategy execution this profit event belongs to.
+     * Handles signal events from live trading only.
+     *
+     * Emitted by: StrategyConnectionService via signalLiveEmitter
+     * Source: StrategyConnectionService.tick() when backtest=false
+     * Frequency: Every tick in live mode
+     *
+     * @param event - Signal state result from live trading
      */
-    strategyName: StrategyName;
+    signalLive(event: IStrategyTickResult): void | Promise<void>;
     /**
-     * Exchange name where this signal is being executed.
-     * Identifies which exchange this profit event belongs to.
+     * Handles signal events from backtest only.
+     *
+     * Emitted by: StrategyConnectionService via signalBacktestEmitter
+     * Source: StrategyConnectionService.backtest() when backtest=true
+     * Frequency: Every candle in backtest mode
+     *
+     * @param event - Signal state result from backtest
      */
-    exchangeName: ExchangeName;
+    signalBacktest(event: IStrategyTickResult): void | Promise<void>;
     /**
-     * Frame name where this signal is being executed.
-     * Identifies which frame this profit event belongs to (empty string for live mode).
+     * Handles breakeven events when stop-loss is moved to entry price.
+     *
+     * Emitted by: BreakevenConnectionService via breakevenSubject
+     * Source: COMMIT_BREAKEVEN_FN callback in BreakevenConnectionService
+     * Frequency: Once per signal when breakeven threshold is reached
+     *
+     * @param event - Breakeven milestone data
      */
-    frameName: FrameName;
+    breakevenAvailable(event: BreakevenContract): void | Promise<void>;
     /**
-     * Complete signal row data with original prices.
-     * Contains all signal information including originalPriceStopLoss, originalPriceTakeProfit, and partialExecuted.
+     * Handles partial profit level events (10%, 20%, 30%, etc).
+     *
+     * Emitted by: PartialConnectionService via partialProfitSubject
+     * Source: COMMIT_PROFIT_FN callback in PartialConnectionService
+     * Frequency: Once per profit level per signal (deduplicated)
+     *
+     * @param event - Profit milestone data with level and price
      */
-    data: IPublicSignalRow;
+    partialProfitAvailable(event: PartialProfitContract): void | Promise<void>;
     /**
-     * Current market price at which this profit level was reached.
-     * Used to calculate actual profit percentage.
+     * Handles partial loss level events (-10%, -20%, -30%, etc).
+     *
+     * Emitted by: PartialConnectionService via partialLossSubject
+     * Source: COMMIT_LOSS_FN callback in PartialConnectionService
+     * Frequency: Once per loss level per signal (deduplicated)
+     *
+     * @param event - Loss milestone data with level and price
      */
-    currentPrice: number;
+    partialLossAvailable(event: PartialLossContract): void | Promise<void>;
     /**
-     * Profit level milestone reached (10, 20, 30, 40, 50, 60, 70, 80, 90, or 100).
-     * Represents percentage profit relative to entry price.
+     * Handles scheduled ping events during scheduled signal monitoring.
      *
-     * @example
-     * ```typescript
-     * // If entry was $50000 and level is 20:
-     * // currentPrice >= $60000 (20% profit)
-     * ```
+     * Emitted by: StrategyConnectionService via schedulePingSubject
+     * Source: CREATE_COMMIT_SCHEDULE_PING_FN callback in StrategyConnectionService
+     * Frequency: Every minute while scheduled signal is waiting for activation
+     *
+     * @param event - Scheduled signal monitoring data
      */
-    level: PartialLevel;
+    pingScheduled(event: SchedulePingContract): void | Promise<void>;
     /**
-     * Execution mode flag.
-     * - true: Event from backtest execution (historical candle data)
-     * - false: Event from live trading (real-time tick)
+     * Handles active ping events during active pending signal monitoring.
+     *
+     * Emitted by: StrategyConnectionService via activePingSubject
+     * Source: CREATE_COMMIT_ACTIVE_PING_FN callback in StrategyConnectionService
+     * Frequency: Every minute while pending signal is active
+     *
+     * @param event - Active pending signal monitoring data
      */
-    backtest: boolean;
+    pingActive(event: ActivePingContract): void | Promise<void>;
     /**
-     * Event timestamp in milliseconds since Unix epoch.
+     * Handles risk rejection events when signals fail risk validation.
      *
-     * Timing semantics:
-     * - Live mode: when.getTime() at the moment profit level was detected
-     * - Backtest mode: candle.timestamp of the candle that triggered the level
+     * Emitted by: RiskConnectionService via riskSubject
+     * Source: COMMIT_REJECTION_FN callback in RiskConnectionService
+     * Frequency: Only when signal is rejected (not emitted for allowed signals)
      *
-     * @example
-     * ```typescript
-     * const eventDate = new Date(event.timestamp);
-     * console.log(`Profit reached at: ${eventDate.toISOString()}`);
-     * ```
+     * @param event - Risk rejection data with reason and context
      */
-    timestamp: number;
-}
-
-/**
- * Contract for partial loss level events.
- *
- * Emitted by partialLossSubject when a signal reaches a loss level milestone (-10%, -20%, -30%, etc).
- * Used for tracking partial stop-loss execution and monitoring strategy drawdown.
- *
- * Events are emitted only once per level per signal (Set-based deduplication in ClientPartial).
- * Multiple levels can be emitted in a single tick if price drops significantly.
- *
- * Consumers:
- * - PartialMarkdownService: Accumulates events for report generation
- * - User callbacks via listenPartialLoss() / listenPartialLossOnce()
- *
- * @example
- * ```typescript
- * import { listenPartialLoss } from "backtest-kit";
- *
- * // Listen to all partial loss events
- * listenPartialLoss((event) => {
- *   console.log(`[${event.backtest ? "Backtest" : "Live"}] Signal ${event.data.id} reached -${event.level}% loss`);
- *   console.log(`Symbol: ${event.symbol}, Price: ${event.currentPrice}`);
- *   console.log(`Position: ${event.data.position}, Entry: ${event.data.priceOpen}`);
- *
- *   // Alert on significant loss
- *   if (event.level >= 30 && !event.backtest) {
- *     console.warn("HIGH LOSS ALERT:", event.data.id);
- *   }
- * });
- *
- * // Wait for first 20% loss level
- * listenPartialLossOnce(
- *   (event) => event.level === 20,
- *   (event) => console.log("20% loss reached:", event.data.id)
- * );
- * ```
- */
-interface PartialLossContract {
-    /**
-     * Trading pair symbol (e.g., "BTCUSDT").
-     * Identifies which market this loss event belongs to.
-     */
-    symbol: string;
-    /**
-     * Strategy name that generated this signal.
-     * Identifies which strategy execution this loss event belongs to.
-     */
-    strategyName: StrategyName;
-    /**
-     * Exchange name where this signal is being executed.
-     * Identifies which exchange this loss event belongs to.
-     */
-    exchangeName: ExchangeName;
-    /**
-     * Frame name where this signal is being executed.
-     * Identifies which frame this loss event belongs to (empty string for live mode).
-     */
-    frameName: FrameName;
-    /**
-     * Complete signal row data with original prices.
-     * Contains all signal information including originalPriceStopLoss, originalPriceTakeProfit, and partialExecuted.
-     */
-    data: IPublicSignalRow;
-    /**
-     * Current market price at which this loss level was reached.
-     * Used to calculate actual loss percentage.
-     */
-    currentPrice: number;
-    /**
-     * Loss level milestone reached (10, 20, 30, 40, 50, 60, 70, 80, 90, or 100).
-     * Represents percentage loss relative to entry price (absolute value).
-     *
-     * Note: Stored as positive number, but represents negative loss.
-     * level=20 means -20% loss from entry price.
-     *
-     * @example
-     * ```typescript
-     * // If entry was $50000 and level is 20:
-     * // currentPrice <= $40000 (-20% loss)
-     * // Level is stored as 20, not -20
-     * ```
-     */
-    level: PartialLevel;
-    /**
-     * Execution mode flag.
-     * - true: Event from backtest execution (historical candle data)
-     * - false: Event from live trading (real-time tick)
-     */
-    backtest: boolean;
+    riskRejection(event: RiskContract): void | Promise<void>;
     /**
-     * Event timestamp in milliseconds since Unix epoch.
-     *
-     * Timing semantics:
-     * - Live mode: when.getTime() at the moment loss level was detected
-     * - Backtest mode: candle.timestamp of the candle that triggered the level
-     *
-     * @example
-     * ```typescript
-     * const eventDate = new Date(event.timestamp);
-     * console.log(`Loss reached at: ${eventDate.toISOString()}`);
+     * Cleans up resources and subscriptions when action handler is no longer needed.
      *
-     * // Calculate time in loss
-     * const entryTime = event.data.pendingAt;
-     * const timeInLoss = event.timestamp - entryTime;
-     * console.log(`In loss for ${timeInLoss / 1000 / 60} minutes`);
-     * ```
+     * Called by: Connection services during shutdown
+     * Use for: Unsubscribing from observables, closing connections, flushing buffers
      */
-    timestamp: number;
+    dispose(): void | Promise<void>;
 }
+/**
+ * Unique action identifier.
+ */
+type ActionName = string;
 
 /**
- * Contract for schedule ping events during scheduled signal monitoring.
- *
- * Emitted by schedulePingSubject every minute when a scheduled signal is being monitored.
- * Used for tracking scheduled signal lifecycle and custom monitoring logic.
- *
- * Events are emitted only when scheduled signal is active (not cancelled, not activated).
- * Allows users to implement custom cancellation logic via onSchedulePing callback.
- *
- * Consumers:
- * - User callbacks via listenSchedulePing() / listenSchedulePingOnce()
- *
- * @example
- * ```typescript
- * import { listenSchedulePing } from "backtest-kit";
- *
- * // Listen to all schedule ping events
- * listenSchedulePing((event) => {
- *   console.log(`[${event.backtest ? "Backtest" : "Live"}] Schedule Ping for ${event.symbol}`);
- *   console.log(`Strategy: ${event.strategyName}, Exchange: ${event.exchangeName}`);
- *   console.log(`Signal ID: ${event.data.id}, priceOpen: ${event.data.priceOpen}`);
- *   console.log(`Timestamp: ${new Date(event.timestamp).toISOString()}`);
- * });
- *
- * // Wait for specific schedule ping
- * listenSchedulePingOnce(
- *   (event) => event.symbol === "BTCUSDT",
- *   (event) => console.log("BTCUSDT schedule ping received:", event.timestamp)
- * );
- * ```
+ * Base fields for all signal commit events.
  */
-interface SchedulePingContract {
-    /**
-     * Trading pair symbol (e.g., "BTCUSDT").
-     * Identifies which market this ping event belongs to.
-     */
+interface SignalCommitBase {
+    /** Trading pair symbol (e.g., "BTCUSDT") */
     symbol: string;
-    /**
-     * Strategy name that is monitoring this scheduled signal.
-     * Identifies which strategy execution this ping event belongs to.
-     */
+    /** Strategy name that generated this signal */
     strategyName: StrategyName;
-    /**
-     * Exchange name where this scheduled signal is being monitored.
-     * Identifies which exchange this ping event belongs to.
-     */
+    /** Exchange name where signal was executed */
     exchangeName: ExchangeName;
-    /**
-     * Complete scheduled signal row data.
-     * Contains all signal information: id, position, priceOpen, priceTakeProfit, priceStopLoss, etc.
-     */
-    data: IScheduledSignalRow;
-    /**
-     * Execution mode flag.
-     * - true: Event from backtest execution (historical candle data)
-     * - false: Event from live trading (real-time tick)
-     */
+    /** Timeframe name (used in backtest mode, empty string in live mode) */
+    frameName: FrameName;
+    /** Whether this event is from backtest mode (true) or live mode (false) */
     backtest: boolean;
+    /** Unique signal identifier (UUID v4) */
+    signalId: string;
+    /** Timestamp from execution context (tick's when or backtest candle timestamp) */
+    timestamp: number;
     /**
-     * Event timestamp in milliseconds since Unix epoch.
-     *
-     * Timing semantics:
-     * - Live mode: when.getTime() at the moment of ping
-     * - Backtest mode: candle.timestamp of the candle being processed
-     *
-     * @example
-     * ```typescript
-     * const eventDate = new Date(event.timestamp);
-     * console.log(`Ping at: ${eventDate.toISOString()}`);
-     * ```
+     * Total number of DCA entries at the time of this event (_entry.length).
+     * 1 = no averaging done (only initial entry). 2+ = averaged positions.
      */
-    timestamp: number;
+    totalEntries: number;
+    /** Original entry price at signal creation (unchanged by DCA averaging). */
+    originalPriceOpen: number;
 }
-
 /**
- * Contract for active ping events during active pending signal monitoring.
- *
- * Emitted by activePingSubject every minute when an active pending signal is being monitored.
- * Used for tracking active signal lifecycle and custom dynamic management logic.
- *
- * Events are emitted only when pending signal is active (not closed yet).
- * Allows users to implement custom management logic via onActivePing callback.
- *
- * Consumers:
- * - User callbacks via listenActivePing() / listenActivePingOnce()
- *
- * @example
- * ```typescript
- * import { listenActivePing } from "backtest-kit";
- *
- * // Listen to all active ping events
- * listenActivePing((event) => {
- *   console.log(`[${event.backtest ? "Backtest" : "Live"}] Active Ping for ${event.symbol}`);
- *   console.log(`Strategy: ${event.strategyName}, Exchange: ${event.exchangeName}`);
- *   console.log(`Signal ID: ${event.data.id}, Position: ${event.data.position}`);
- *   console.log(`Timestamp: ${new Date(event.timestamp).toISOString()}`);
- * });
- *
- * // Wait for specific active ping
- * listenActivePingOnce(
- *   (event) => event.symbol === "BTCUSDT",
- *   (event) => console.log("BTCUSDT active ping received:", event.timestamp)
- * );
- * ```
- */
-interface ActivePingContract {
-    /**
-     * Trading pair symbol (e.g., "BTCUSDT").
-     * Identifies which market this ping event belongs to.
-     */
-    symbol: string;
-    /**
-     * Strategy name that is monitoring this active pending signal.
-     * Identifies which strategy execution this ping event belongs to.
-     */
-    strategyName: StrategyName;
-    /**
-     * Exchange name where this active pending signal is being monitored.
-     * Identifies which exchange this ping event belongs to.
-     */
-    exchangeName: ExchangeName;
-    /**
-     * Complete pending signal row data.
-     * Contains all signal information: id, position, priceOpen, priceTakeProfit, priceStopLoss, etc.
-     */
-    data: ISignalRow;
-    /**
-     * Execution mode flag.
-     * - true: Event from backtest execution (historical candle data)
-     * - false: Event from live trading (real-time tick)
-     */
-    backtest: boolean;
-    /**
-     * Event timestamp in milliseconds since Unix epoch.
-     *
-     * Timing semantics:
-     * - Live mode: when.getTime() at the moment of ping
-     * - Backtest mode: candle.timestamp of the candle being processed
-     *
-     * @example
-     * ```typescript
-     * const eventDate = new Date(event.timestamp);
-     * console.log(`Active Ping at: ${eventDate.toISOString()}`);
-     * ```
-     */
-    timestamp: number;
-}
-
-/**
- * Contract for risk rejection events.
- *
- * Emitted by riskSubject ONLY when a signal is REJECTED due to risk validation failure.
- * Used for tracking actual risk violations and monitoring rejected signals.
- *
- * Events are emitted only when risk limits are violated (not for allowed signals).
- * This prevents spam and allows focusing on actual risk management interventions.
- *
- * Consumers:
- * - RiskMarkdownService: Accumulates rejection events for report generation
- * - User callbacks via listenRisk() / listenRiskOnce()
- *
- * @example
- * ```typescript
- * import { listenRisk } from "backtest-kit";
- *
- * // Listen to all risk rejection events
- * listenRisk((event) => {
- *   console.log(`[RISK REJECTED] Signal for ${event.symbol}`);
- *   console.log(`Strategy: ${event.strategyName}`);
- *   console.log(`Active positions: ${event.activePositionCount}`);
- *   console.log(`Price: ${event.currentPrice}`);
- *   console.log(`Timestamp: ${new Date(event.timestamp).toISOString()}`);
- * });
- *
- * // Alert on risk rejections for specific symbol
- * listenRisk((event) => {
- *   if (event.symbol === "BTCUSDT") {
- *     console.warn("BTC signal rejected due to risk limits!");
- *   }
- * });
- * ```
- */
-interface RiskContract {
-    /**
-     * Trading pair symbol (e.g., "BTCUSDT").
-     * Identifies which market this rejected signal belongs to.
-     */
-    symbol: string;
-    /**
-     * Pending signal to apply.
-     * Contains signal details (position, priceOpen, priceTakeProfit, priceStopLoss, etc).
-     */
-    currentSignal: ISignalDto;
-    /**
-     * Strategy name requesting to open a position.
-     * Identifies which strategy attempted to create the signal.
-     */
-    strategyName: StrategyName;
-    /**
-     * Frame name used in backtest execution.
-     * Identifies which frame this signal was for in backtest execution.
-     */
-    frameName: FrameName;
-    /**
-     * Exchange name.
-     * Identifies which exchange this signal was for.
-     */
-    exchangeName: ExchangeName;
-    /**
-     * Current VWAP price at the time of rejection.
-     * Market price when risk check was performed.
-     */
-    currentPrice: number;
-    /**
-     * Number of currently active positions across all strategies at rejection time.
-     * Used to track portfolio-level exposure when signal was rejected.
-     */
-    activePositionCount: number;
-    /**
-     * Unique identifier for this rejection instance.
-     * Generated by ClientRisk for tracking and debugging purposes.
-     * Null if validation threw exception without custom ID.
-     */
-    rejectionId: string | null;
-    /**
-     * Human-readable reason why the signal was rejected.
-     * Captured from IRiskValidation.note or error message.
-     *
-     * @example
-     * ```typescript
-     * console.log(`Rejection reason: ${event.rejectionNote}`);
-     * // Output: "Rejection reason: Max 3 positions allowed"
-     * ```
-     */
-    rejectionNote: string;
-    /**
-     * Event timestamp in milliseconds since Unix epoch.
-     * Represents when the signal was rejected.
-     *
-     * @example
-     * ```typescript
-     * const eventDate = new Date(event.timestamp);
-     * console.log(`Signal rejected at: ${eventDate.toISOString()}`);
-     * ```
-     */
-    timestamp: number;
-    /**
-     * Whether this event is from backtest mode (true) or live mode (false).
-     * Used to separate backtest and live risk rejection tracking.
-     */
-    backtest: boolean;
-}
-
-/**
- * Constructor type for action handlers with strategy context.
- *
- * @param strategyName - Strategy identifier (e.g., "rsi_divergence", "macd_cross")
- * @param frameName - Timeframe identifier (e.g., "1m", "5m", "1h")
- * @param backtest - True for backtest mode, false for live trading
- * @returns Partial implementation of IAction (only required handlers)
- *
- * @example
- * ```typescript
- * class TelegramNotifier implements Partial<IAction> {
- *   constructor(
- *     private strategyName: StrategyName,
- *     private frameName: FrameName,
- *     private backtest: boolean
- *   ) {}
- *
- *   signal(event: IStrategyTickResult): void {
- *     if (!this.backtest && event.state === 'opened') {
- *       telegram.send(`[${this.strategyName}/${this.frameName}] New signal`);
- *     }
- *   }
- * }
- *
- * const actionCtors: TActionCtor[] = [TelegramNotifier, ReduxLogger];
- * ```
- */
-type TActionCtor = new (strategyName: StrategyName, frameName: FrameName, actionName: ActionName, backtest: boolean) => Partial<IPublicAction>;
-/**
- * Action parameters passed to ClientAction constructor.
- * Combines schema with runtime dependencies and execution context.
- *
- * Extended from IActionSchema with:
- * - Logger instance for debugging and monitoring
- * - Strategy context (strategyName, frameName)
- * - Runtime environment flags
- *
- * @example
- * ```typescript
- * const params: IActionParams = {
- *   actionName: "telegram-notifier",
- *   handler: TelegramNotifier,
- *   callbacks: { onInit, onDispose, onSignal },
- *   logger: loggerService,
- *   strategyName: "rsi_divergence",
- *   frameName: "1h"
- * };
- *
- * const actionClient = new ClientAction(params);
- * ```
- */
-interface IActionParams extends IActionSchema {
-    /** Logger service for debugging and monitoring action execution */
-    logger: ILogger;
-    /** Strategy identifier this action is attached to */
-    strategyName: StrategyName;
-    /** Exchange name (e.g., "binance") */
-    exchangeName: ExchangeName;
-    /** Timeframe identifier this action is attached to */
-    frameName: FrameName;
-    /** Whether running in backtest mode */
-    backtest: boolean;
-}
-/**
- * Lifecycle and event callbacks for action handlers.
- *
- * Provides hooks for initialization, disposal, and event handling.
- * All callbacks are optional and support both sync and async execution.
- *
- * Use cases:
- * - Resource initialization (database connections, file handles)
- * - Resource cleanup (close connections, flush buffers)
- * - Event logging and monitoring
- * - State persistence
- *
- * @example
- * ```typescript
- * const callbacks: IActionCallbacks = {
- *   onInit: async (strategyName, frameName, backtest) => {
- *     console.log(`[${strategyName}/${frameName}] Action initialized (backtest=${backtest})`);
- *     await db.connect();
- *   },
- *   onSignal: (event, strategyName, frameName, backtest) => {
- *     if (event.action === 'opened') {
- *       console.log(`New signal opened: ${event.signal.id}`);
- *     }
- *   },
- *   onDispose: async (strategyName, frameName, backtest) => {
- *     await db.disconnect();
- *     console.log(`[${strategyName}/${frameName}] Action disposed`);
- *   }
- * };
- * ```
- */
-interface IActionCallbacks {
-    /**
-     * Called when action handler is initialized.
-     *
-     * Use for:
-     * - Opening database connections
-     * - Initializing external services
-     * - Loading persisted state
-     * - Setting up subscriptions
-     *
-     * @param actionName - Action identifier
-     * @param strategyName - Strategy identifier
-     * @param frameName - Timeframe identifier
-     * @param backtest - True for backtest mode, false for live trading
-     */
-    onInit(actionName: ActionName, strategyName: StrategyName, frameName: FrameName, backtest: boolean): void | Promise<void>;
-    /**
-     * Called when action handler is disposed.
-     *
-     * Use for:
-     * - Closing database connections
-     * - Flushing buffers
-     * - Saving state to disk
-     * - Unsubscribing from observables
-     *
-     * @param actionName - Action identifier
-     * @param strategyName - Strategy identifier
-     * @param frameName - Timeframe identifier
-     * @param backtest - True for backtest mode, false for live trading
-     */
-    onDispose(actionName: ActionName, strategyName: StrategyName, frameName: FrameName, backtest: boolean): void | Promise<void>;
-    /**
-     * Called on signal events from all modes (live + backtest).
-     *
-     * Triggered by: StrategyConnectionService via signalEmitter
-     * Frequency: Every tick/candle when strategy is evaluated
-     *
-     * @param event - Signal state result (idle, scheduled, opened, active, closed, cancelled)
-     * @param actionName - Action identifier
-     * @param strategyName - Strategy identifier
-     * @param frameName - Timeframe identifier
-     * @param backtest - True for backtest mode, false for live trading
-     */
-    onSignal(event: IStrategyTickResult, actionName: ActionName, strategyName: StrategyName, frameName: FrameName, backtest: boolean): void | Promise<void>;
-    /**
-     * Called on signal events from live trading only.
-     *
-     * Triggered by: StrategyConnectionService via signalLiveEmitter
-     * Frequency: Every tick in live mode
-     *
-     * @param event - Signal state result from live trading
-     * @param actionName - Action identifier
-     * @param strategyName - Strategy identifier
-     * @param frameName - Timeframe identifier
-     * @param backtest - Always false (live mode only)
-     */
-    onSignalLive(event: IStrategyTickResult, actionName: ActionName, strategyName: StrategyName, frameName: FrameName, backtest: boolean): void | Promise<void>;
-    /**
-     * Called on signal events from backtest only.
-     *
-     * Triggered by: StrategyConnectionService via signalBacktestEmitter
-     * Frequency: Every candle in backtest mode
-     *
-     * @param event - Signal state result from backtest
-     * @param actionName - Action identifier
-     * @param strategyName - Strategy identifier
-     * @param frameName - Timeframe identifier
-     * @param backtest - Always true (backtest mode only)
-     */
-    onSignalBacktest(event: IStrategyTickResult, actionName: ActionName, strategyName: StrategyName, frameName: FrameName, backtest: boolean): void | Promise<void>;
-    /**
-     * Called when breakeven is triggered (stop-loss moved to entry price).
-     *
-     * Triggered by: BreakevenConnectionService via breakevenSubject
-     * Frequency: Once per signal when breakeven threshold is reached
-     *
-     * @param event - Breakeven milestone data
-     * @param actionName - Action identifier
-     * @param strategyName - Strategy identifier
-     * @param frameName - Timeframe identifier
-     * @param backtest - True for backtest mode, false for live trading
-     */
-    onBreakevenAvailable(event: BreakevenContract, actionName: ActionName, strategyName: StrategyName, frameName: FrameName, backtest: boolean): void | Promise<void>;
-    /**
-     * Called when partial profit level is reached (10%, 20%, 30%, etc).
-     *
-     * Triggered by: PartialConnectionService via partialProfitSubject
-     * Frequency: Once per profit level per signal (deduplicated)
-     *
-     * @param event - Profit milestone data with level and price
-     * @param actionName - Action identifier
-     * @param strategyName - Strategy identifier
-     * @param frameName - Timeframe identifier
-     * @param backtest - True for backtest mode, false for live trading
-     */
-    onPartialProfitAvailable(event: PartialProfitContract, actionName: ActionName, strategyName: StrategyName, frameName: FrameName, backtest: boolean): void | Promise<void>;
-    /**
-     * Called when partial loss level is reached (-10%, -20%, -30%, etc).
-     *
-     * Triggered by: PartialConnectionService via partialLossSubject
-     * Frequency: Once per loss level per signal (deduplicated)
-     *
-     * @param event - Loss milestone data with level and price
-     * @param actionName - Action identifier
-     * @param strategyName - Strategy identifier
-     * @param frameName - Timeframe identifier
-     * @param backtest - True for backtest mode, false for live trading
-     */
-    onPartialLossAvailable(event: PartialLossContract, actionName: ActionName, strategyName: StrategyName, frameName: FrameName, backtest: boolean): void | Promise<void>;
-    /**
-     * Called during scheduled signal monitoring (every minute while waiting for activation).
-     *
-     * Triggered by: StrategyConnectionService via schedulePingSubject
-     * Frequency: Every minute while scheduled signal is waiting
-     *
-     * @param event - Scheduled signal monitoring data
-     * @param actionName - Action identifier
-     * @param strategyName - Strategy identifier
-     * @param frameName - Timeframe identifier
-     * @param backtest - True for backtest mode, false for live trading
-     */
-    onPingScheduled(event: SchedulePingContract, actionName: ActionName, strategyName: StrategyName, frameName: FrameName, backtest: boolean): void | Promise<void>;
-    /**
-     * Called during active pending signal monitoring (every minute while position is active).
-     *
-     * Triggered by: StrategyConnectionService via activePingSubject
-     * Frequency: Every minute while pending signal is active
-     *
-     * @param event - Active pending signal monitoring data
-     * @param actionName - Action identifier
-     * @param strategyName - Strategy identifier
-     * @param frameName - Timeframe identifier
-     * @param backtest - True for backtest mode, false for live trading
-     */
-    onPingActive(event: ActivePingContract, actionName: ActionName, strategyName: StrategyName, frameName: FrameName, backtest: boolean): void | Promise<void>;
-    /**
-     * Called when signal is rejected by risk management.
-     *
-     * Triggered by: RiskConnectionService via riskSubject
-     * Frequency: Only when signal fails risk validation (not emitted for allowed signals)
-     *
-     * @param event - Risk rejection data with reason and context
-     * @param actionName - Action identifier
-     * @param strategyName - Strategy identifier
-     * @param frameName - Timeframe identifier
-     * @param backtest - True for backtest mode, false for live trading
-     */
-    onRiskRejection(event: RiskContract, actionName: ActionName, strategyName: StrategyName, frameName: FrameName, backtest: boolean): void | Promise<void>;
-}
-/**
- * Action schema registered via addActionSchema().
- * Defines event handler implementation and lifecycle callbacks for state management integration.
- *
- * Actions provide a way to attach custom event handlers to strategies for:
- * - State management (Redux, Zustand, MobX)
- * - Event logging and monitoring
- * - Real-time notifications (Telegram, Discord, email)
- * - Analytics and metrics collection
- * - Custom business logic triggers
- *
- * Each action instance is created per strategy-frame pair and receives all events
- * emitted during strategy execution. Multiple actions can be attached to a single strategy.
- *
- * @example
- * ```typescript
- * import { addActionSchema } from "backtest-kit";
- *
- * // Define action handler class
- * class TelegramNotifier implements Partial<IAction> {
- *   constructor(
- *     private strategyName: StrategyName,
- *     private frameName: FrameName,
- *     private backtest: boolean
- *   ) {}
- *
- *   signal(event: IStrategyTickResult): void {
- *     if (!this.backtest && event.action === 'opened') {
- *       telegram.send(`[${this.strategyName}/${this.frameName}] New signal`);
- *     }
- *   }
- *
- *   dispose(): void {
- *     telegram.close();
- *   }
- * }
- *
- * // Register action schema
- * addActionSchema({
- *   actionName: "telegram-notifier",
- *   handler: TelegramNotifier,
- *   callbacks: {
- *     onInit: async (strategyName, frameName, backtest) => {
- *       console.log(`Telegram notifier initialized for ${strategyName}/${frameName}`);
- *     },
- *     onSignal: (event, strategyName, frameName, backtest) => {
- *       console.log(`Signal event: ${event.action}`);
- *     }
- *   }
- * });
- * ```
- */
-interface IActionSchema {
-    /** Unique action identifier for registration */
-    actionName: ActionName;
-    /** Optional developer note for documentation */
-    note?: string;
-    /** Action handler constructor (instantiated per strategy-frame pair) */
-    handler: TActionCtor | Partial<IPublicAction>;
-    /** Optional lifecycle and event callbacks */
-    callbacks?: Partial<IActionCallbacks>;
-}
-/**
- * Public action interface for custom action handler implementations.
- *
- * Extends IAction with an initialization lifecycle method.
- * Action handlers implement this interface to receive strategy events and perform custom logic.
- *
- * Lifecycle:
- * 1. Constructor called with (strategyName, frameName, actionName)
- * 2. init() called once for async initialization (setup connections, load resources)
- * 3. Event methods called as strategy executes (signal, breakeven, partialProfit, etc.)
- * 4. dispose() called once for cleanup (close connections, flush buffers)
- *
- * Key features:
- * - init() for async initialization (database connections, API clients, file handles)
- * - All IAction methods available for event handling
- * - dispose() guaranteed to run exactly once via singleshot pattern
- *
- * Common use cases:
- * - State management: Redux/Zustand store integration
- * - Notifications: Telegram/Discord/Email alerts
- * - Logging: Custom event tracking and monitoring
- * - Analytics: Metrics collection and reporting
- * - External systems: Database writes, API calls, file operations
- *
- * @example
- * ```typescript
- * class TelegramNotifier implements Partial<IPublicAction> {
- *   private bot: TelegramBot | null = null;
- *
- *   constructor(
- *     private strategyName: string,
- *     private frameName: string,
- *     private actionName: string
- *   ) {}
- *
- *   // Called once during initialization
- *   async init() {
- *     this.bot = new TelegramBot(process.env.TELEGRAM_TOKEN);
- *     await this.bot.connect();
- *   }
- *
- *   // Called on every signal event
- *   async signal(event: IStrategyTickResult) {
- *     if (event.action === 'opened') {
- *       await this.bot.send(
- *         `[${this.strategyName}/${this.frameName}] Signal opened: ${event.signal.side}`
- *       );
- *     }
- *   }
- *
- *   // Called once during cleanup
- *   async dispose() {
- *     await this.bot?.disconnect();
- *     this.bot = null;
- *   }
- * }
- * ```
- *
- * @see IAction for all available event methods
- * @see TActionCtor for constructor signature requirements
- * @see ClientAction for internal wrapper that manages lifecycle
- */
-type IPublicAction = {
-    [key in keyof IAction]?: IAction[key];
-} & {
-    init?(): void | Promise<void>;
-};
-/**
- * Action interface for state manager integration.
- *
- * Provides methods to handle all events emitted by connection services.
- * Each method corresponds to a specific event type emitted via .next() calls.
- *
- * Use this interface to implement custom state management logic:
- * - Redux/Zustand action dispatchers
- * - Event logging systems
- * - Real-time monitoring dashboards
- * - Analytics and metrics collection
- *
- * @example
- * ```typescript
- * class ReduxStateManager implements IAction {
- *   constructor(private store: Store) {}
- *
- *   signal(event: IStrategyTickResult): void {
- *     this.store.dispatch({ type: 'SIGNAL', payload: event });
- *   }
- *
- *   breakeven(event: BreakevenContract): void {
- *     this.store.dispatch({ type: 'BREAKEVEN', payload: event });
- *   }
- *
- *   // ... implement other methods
- * }
- * ```
- */
-interface IAction {
-    /**
-     * Handles signal events from all modes (live + backtest).
-     *
-     * Emitted by: StrategyConnectionService via signalEmitter
-     * Source: StrategyConnectionService.tick() and StrategyConnectionService.backtest()
-     * Frequency: Every tick/candle when strategy is evaluated
-     *
-     * @param event - Signal state result (idle, scheduled, opened, active, closed, cancelled)
-     */
-    signal(event: IStrategyTickResult): void | Promise<void>;
-    /**
-     * Handles signal events from live trading only.
-     *
-     * Emitted by: StrategyConnectionService via signalLiveEmitter
-     * Source: StrategyConnectionService.tick() when backtest=false
-     * Frequency: Every tick in live mode
-     *
-     * @param event - Signal state result from live trading
-     */
-    signalLive(event: IStrategyTickResult): void | Promise<void>;
-    /**
-     * Handles signal events from backtest only.
-     *
-     * Emitted by: StrategyConnectionService via signalBacktestEmitter
-     * Source: StrategyConnectionService.backtest() when backtest=true
-     * Frequency: Every candle in backtest mode
-     *
-     * @param event - Signal state result from backtest
-     */
-    signalBacktest(event: IStrategyTickResult): void | Promise<void>;
-    /**
-     * Handles breakeven events when stop-loss is moved to entry price.
-     *
-     * Emitted by: BreakevenConnectionService via breakevenSubject
-     * Source: COMMIT_BREAKEVEN_FN callback in BreakevenConnectionService
-     * Frequency: Once per signal when breakeven threshold is reached
-     *
-     * @param event - Breakeven milestone data
-     */
-    breakevenAvailable(event: BreakevenContract): void | Promise<void>;
-    /**
-     * Handles partial profit level events (10%, 20%, 30%, etc).
-     *
-     * Emitted by: PartialConnectionService via partialProfitSubject
-     * Source: COMMIT_PROFIT_FN callback in PartialConnectionService
-     * Frequency: Once per profit level per signal (deduplicated)
-     *
-     * @param event - Profit milestone data with level and price
-     */
-    partialProfitAvailable(event: PartialProfitContract): void | Promise<void>;
-    /**
-     * Handles partial loss level events (-10%, -20%, -30%, etc).
-     *
-     * Emitted by: PartialConnectionService via partialLossSubject
-     * Source: COMMIT_LOSS_FN callback in PartialConnectionService
-     * Frequency: Once per loss level per signal (deduplicated)
-     *
-     * @param event - Loss milestone data with level and price
-     */
-    partialLossAvailable(event: PartialLossContract): void | Promise<void>;
-    /**
-     * Handles scheduled ping events during scheduled signal monitoring.
-     *
-     * Emitted by: StrategyConnectionService via schedulePingSubject
-     * Source: CREATE_COMMIT_SCHEDULE_PING_FN callback in StrategyConnectionService
-     * Frequency: Every minute while scheduled signal is waiting for activation
-     *
-     * @param event - Scheduled signal monitoring data
-     */
-    pingScheduled(event: SchedulePingContract): void | Promise<void>;
-    /**
-     * Handles active ping events during active pending signal monitoring.
-     *
-     * Emitted by: StrategyConnectionService via activePingSubject
-     * Source: CREATE_COMMIT_ACTIVE_PING_FN callback in StrategyConnectionService
-     * Frequency: Every minute while pending signal is active
-     *
-     * @param event - Active pending signal monitoring data
-     */
-    pingActive(event: ActivePingContract): void | Promise<void>;
-    /**
-     * Handles risk rejection events when signals fail risk validation.
-     *
-     * Emitted by: RiskConnectionService via riskSubject
-     * Source: COMMIT_REJECTION_FN callback in RiskConnectionService
-     * Frequency: Only when signal is rejected (not emitted for allowed signals)
-     *
-     * @param event - Risk rejection data with reason and context
-     */
-    riskRejection(event: RiskContract): void | Promise<void>;
-    /**
-     * Cleans up resources and subscriptions when action handler is no longer needed.
-     *
-     * Called by: Connection services during shutdown
-     * Use for: Unsubscribing from observables, closing connections, flushing buffers
-     */
-    dispose(): void | Promise<void>;
-}
-/**
- * Unique action identifier.
- */
-type ActionName = string;
-
-/**
- * Base fields for all signal commit events.
- */
-interface SignalCommitBase {
-    /** Trading pair symbol (e.g., "BTCUSDT") */
-    symbol: string;
-    /** Strategy name that generated this signal */
-    strategyName: StrategyName;
-    /** Exchange name where signal was executed */
-    exchangeName: ExchangeName;
-    /** Timeframe name (used in backtest mode, empty string in live mode) */
-    frameName: FrameName;
-    /** Whether this event is from backtest mode (true) or live mode (false) */
-    backtest: boolean;
-    /** Unique signal identifier (UUID v4) */
-    signalId: string;
-    /** Timestamp from execution context (tick's when or backtest candle timestamp) */
-    timestamp: number;
-    /**
-     * Total number of DCA entries at the time of this event (_entry.length).
-     * 1 = no averaging done (only initial entry). 2+ = averaged positions.
-     */
-    totalEntries: number;
-    /** Original entry price at signal creation (unchanged by DCA averaging). */
-    originalPriceOpen: number;
-}
-/**
- * Cancel scheduled signal event.
+ * Cancel scheduled signal event.
  */
 interface CancelScheduledCommit extends SignalCommitBase {
     /** Discriminator for cancel-scheduled action */
@@ -3177,305 +2639,847 @@ interface IStrategy {
      *
      * @example
      * ```typescript
-     * // Activate scheduled signal without waiting for priceOpen
-     * await strategy.activateScheduled("BTCUSDT", false, "user-activate-123");
-     * // Scheduled signal becomes pending signal immediately
+     * // Activate scheduled signal without waiting for priceOpen
+     * await strategy.activateScheduled("BTCUSDT", false, "user-activate-123");
+     * // Scheduled signal becomes pending signal immediately
+     * ```
+     */
+    activateScheduled: (symbol: string, backtest: boolean, activateId?: string) => Promise<void>;
+    /**
+     * Closes the pending signal without stopping the strategy.
+     *
+     * Clears the pending signal (active position).
+     * Does NOT affect scheduled signals or strategy operation.
+     * Does NOT set stop flag - strategy can continue generating new signals.
+     *
+     * Use case: Close an active position that is no longer desired without stopping the entire strategy.
+     *
+     * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+     * @param backtest - Whether running in backtest mode
+     * @param closeId - Optional identifier for this close operation
+     * @returns Promise that resolves when pending signal is cleared
+     *
+     * @example
+     * ```typescript
+     * // Close pending signal without stopping strategy
+     * await strategy.closePending("BTCUSDT", false, "user-close-123");
+     * // Strategy continues, can generate new signals
+     * ```
+     */
+    closePending: (symbol: string, backtest: boolean, closeId?: string) => Promise<void>;
+    /**
+     * Executes partial close at profit level (moving toward TP).
+     *
+     * Closes specified percentage of position at current price.
+     * Updates _tpClosed, _totalClosed, and _partialHistory state.
+     * Persists updated signal state for crash recovery.
+     *
+     * Validations:
+     * - Throws if no pending signal exists
+     * - Throws if called on scheduled signal (not yet activated)
+     * - Throws if percentToClose <= 0 or > 100
+     * - Returns false if _totalClosed + percentToClose > 100 (prevents over-closing)
+     *
+     * Use case: User-controlled partial close triggered from onPartialProfit callback.
+     *
+     * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+     * @param percentToClose - Absolute percentage of position to close (0-100)
+     * @param currentPrice - Current market price for partial close
+     * @param backtest - Whether running in backtest mode
+     * @returns Promise<boolean> - true if partial close executed, false if skipped
+     *
+     * @example
+     * ```typescript
+     * callbacks: {
+     *   onPartialProfit: async (symbol, signal, currentPrice, percentTp, backtest) => {
+     *     if (percentTp >= 50) {
+     *       const success = await strategy.partialProfit(symbol, 25, currentPrice, backtest);
+     *       if (success) {
+     *         console.log('Partial profit executed');
+     *       }
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    partialProfit: (symbol: string, percentToClose: number, currentPrice: number, backtest: boolean) => Promise<boolean>;
+    /**
+     * Executes partial close at loss level (moving toward SL).
+     *
+     * Closes specified percentage of position at current price.
+     * Updates _slClosed, _totalClosed, and _partialHistory state.
+     * Persists updated signal state for crash recovery.
+     *
+     * Validations:
+     * - Throws if no pending signal exists
+     * - Throws if called on scheduled signal (not yet activated)
+     * - Throws if percentToClose <= 0 or > 100
+     * - Returns false if _totalClosed + percentToClose > 100 (prevents over-closing)
+     *
+     * Use case: User-controlled partial close triggered from onPartialLoss callback.
+     *
+     * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+     * @param percentToClose - Absolute percentage of position to close (0-100)
+     * @param currentPrice - Current market price for partial close
+     * @param backtest - Whether running in backtest mode
+     * @returns Promise<boolean> - true if partial close executed, false if skipped
+     *
+     * @example
+     * ```typescript
+     * callbacks: {
+     *   onPartialLoss: async (symbol, signal, currentPrice, percentSl, backtest) => {
+     *     if (percentSl >= 80) {
+     *       const success = await strategy.partialLoss(symbol, 50, currentPrice, backtest);
+     *       if (success) {
+     *         console.log('Partial loss executed');
+     *       }
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    partialLoss: (symbol: string, percentToClose: number, currentPrice: number, backtest: boolean) => Promise<boolean>;
+    /**
+     * Adjusts trailing stop-loss by shifting distance between entry and original SL.
+     *
+     * CRITICAL: Always calculates from ORIGINAL SL, not from current trailing SL.
+     * This prevents error accumulation on repeated calls.
+     * Larger percentShift ABSORBS smaller one (updates only towards better protection).
+     *
+     * Calculates new SL based on percentage shift of the ORIGINAL distance (entry - originalSL):
+     * - Negative %: tightens stop (moves SL closer to entry, reduces risk)
+     * - Positive %: loosens stop (moves SL away from entry, allows more drawdown)
+     *
+     * For LONG position (entry=100, originalSL=90, distance=10%):
+     * - percentShift = -50: newSL = 100 - 10%*(1-0.5) = 95 (5% distance, tighter)
+     * - percentShift = +20: newSL = 100 - 10%*(1+0.2) = 88 (12% distance, looser)
+     *
+     * For SHORT position (entry=100, originalSL=110, distance=10%):
+     * - percentShift = -50: newSL = 100 + 10%*(1-0.5) = 105 (5% distance, tighter)
+     * - percentShift = +20: newSL = 100 + 10%*(1+0.2) = 112 (12% distance, looser)
+     *
+     * Absorption behavior:
+     * - First call: sets trailing SL unconditionally
+     * - Subsequent calls: updates only if new SL is BETTER (protects more profit)
+     * - For LONG: only accepts HIGHER SL (never moves down, closer to entry wins)
+     * - For SHORT: only accepts LOWER SL (never moves up, closer to entry wins)
+     * - Stores in _trailingPriceStopLoss, original priceStopLoss always preserved
+     *
+     * Validations:
+     * - Throws if no pending signal exists
+     * - Throws if percentShift < -100 or > 100
+     * - Throws if percentShift === 0
+     * - Skips if new SL would cross entry price
+     * - Skips if currentPrice already crossed new SL level (price intrusion protection)
+     *
+     * Use case: User-controlled trailing stop triggered from onPartialProfit callback.
+     *
+     * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+     * @param percentShift - Percentage shift of ORIGINAL SL distance [-100, 100], excluding 0
+     * @param currentPrice - Current market price to check for intrusion
+     * @param backtest - Whether running in backtest mode
+     * @returns Promise<boolean> - true if trailing SL was set/updated, false if rejected
+     *
+     * @example
+     * ```typescript
+     * callbacks: {
+     *   onPartialProfit: async (symbol, signal, currentPrice, percentTp, backtest) => {
+     *     if (percentTp >= 50) {
+     *       // LONG: entry=100, originalSL=90, distance=10%
+     *
+     *       // First call: tighten by 5%
+     *       const success1 = await strategy.trailingStop(symbol, -5, currentPrice, backtest);
+     *       // success1 = true, newDistance = 10% - 5% = 5%, newSL = 95
+     *
+     *       // Second call: try weaker protection
+     *       const success2 = await strategy.trailingStop(symbol, -3, currentPrice, backtest);
+     *       // success2 = false (SKIPPED: newSL=97 < 95, worse protection, larger % absorbs smaller)
+     *
+     *       // Third call: stronger protection
+     *       const success3 = await strategy.trailingStop(symbol, -7, currentPrice, backtest);
+     *       // success3 = true (ACCEPTED: newDistance = 3%, newSL = 97 > 95, better protection)
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    trailingStop: (symbol: string, percentShift: number, currentPrice: number, backtest: boolean) => Promise<boolean>;
+    /**
+     * Adjusts the trailing take-profit distance for an active pending signal.
+     *
+     * CRITICAL: Always calculates from ORIGINAL TP, not from current trailing TP.
+     * This prevents error accumulation on repeated calls.
+     * Larger percentShift ABSORBS smaller one (updates only towards more conservative TP).
+     *
+     * Updates the take-profit distance by a percentage adjustment relative to the ORIGINAL TP distance.
+     * Negative percentShift brings TP closer to entry (more conservative).
+     * Positive percentShift moves TP further from entry (more aggressive).
+     *
+     * Absorption behavior:
+     * - First call: sets trailing TP unconditionally
+     * - Subsequent calls: updates only if new TP is MORE CONSERVATIVE (closer to entry)
+     * - For LONG: only accepts LOWER TP (never moves up, closer to entry wins)
+     * - For SHORT: only accepts HIGHER TP (never moves down, closer to entry wins)
+     * - Stores in _trailingPriceTakeProfit, original priceTakeProfit always preserved
+     *
+     * Price intrusion protection: If current price has already crossed the new TP level,
+     * the update is skipped to prevent immediate TP triggering.
+     *
+     * @param symbol - Trading pair symbol
+     * @param percentShift - Percentage adjustment to ORIGINAL TP distance (-100 to 100)
+     * @param currentPrice - Current market price to check for intrusion
+     * @param backtest - Whether running in backtest mode
+     * @returns Promise<boolean> - true if trailing TP was set/updated, false if rejected
+     *
+     * @example
+     * ```typescript
+     * callbacks: {
+     *   onPartialProfit: async (symbol, signal, currentPrice, percentTp, backtest) => {
+     *     // LONG: entry=100, originalTP=110, distance=10%, currentPrice=102
+     *
+     *     // First call: bring TP closer by 3%
+     *     const success1 = await strategy.trailingTake(symbol, -3, currentPrice, backtest);
+     *     // success1 = true, newDistance = 10% - 3% = 7%, newTP = 107
+     *
+     *     // Second call: try to move TP further (less conservative)
+     *     const success2 = await strategy.trailingTake(symbol, 2, currentPrice, backtest);
+     *     // success2 = false (SKIPPED: newTP=112 > 107, less conservative, larger % absorbs smaller)
+     *
+     *     // Third call: even more conservative
+     *     const success3 = await strategy.trailingTake(symbol, -5, currentPrice, backtest);
+     *     // success3 = true (ACCEPTED: newDistance = 5%, newTP = 105 < 107, more conservative)
+     *   }
+     * }
+     * ```
+     */
+    trailingTake: (symbol: string, percentShift: number, currentPrice: number, backtest: boolean) => Promise<boolean>;
+    /**
+     * Moves stop-loss to breakeven (entry price) when price reaches threshold.
+     *
+     * Moves SL to entry price (zero-risk position) when current price has moved
+     * far enough in profit direction to cover transaction costs (slippage + fees).
+     * Threshold is calculated as: (CC_PERCENT_SLIPPAGE + CC_PERCENT_FEE) * 2
+     *
+     * Behavior:
+     * - Returns true if SL was moved to breakeven
+     * - Returns false if conditions not met (threshold not reached or already at breakeven)
+     * - Uses _trailingPriceStopLoss to store breakeven SL (preserves original priceStopLoss)
+     * - Only moves SL once per position (idempotent - safe to call multiple times)
+     *
+     * For LONG position (entry=100, slippage=0.1%, fee=0.1%):
+     * - Threshold: (0.1 + 0.1) * 2 = 0.4%
+     * - Breakeven available when price >= 100.4 (entry + 0.4%)
+     * - Moves SL from original (e.g. 95) to 100 (breakeven)
+     * - Returns true on first successful move, false on subsequent calls
+     *
+     * For SHORT position (entry=100, slippage=0.1%, fee=0.1%):
+     * - Threshold: (0.1 + 0.1) * 2 = 0.4%
+     * - Breakeven available when price <= 99.6 (entry - 0.4%)
+     * - Moves SL from original (e.g. 105) to 100 (breakeven)
+     * - Returns true on first successful move, false on subsequent calls
+     *
+     * Validations:
+     * - Throws if no pending signal exists
+     * - Throws if currentPrice is not a positive finite number
+     *
+     * Use case: User-controlled breakeven protection triggered from onPartialProfit callback.
+     *
+     * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+     * @param currentPrice - Current market price to check threshold
+     * @param backtest - Whether running in backtest mode
+     * @returns Promise<boolean> - true if breakeven was set, false if conditions not met
+     *
+     * @example
+     * ```typescript
+     * callbacks: {
+     *   onPartialProfit: async (symbol, signal, currentPrice, percentTp, backtest) => {
+     *     // Try to move SL to breakeven when threshold reached
+     *     const movedToBreakeven = await strategy.breakeven(symbol, currentPrice, backtest);
+     *     if (movedToBreakeven) {
+     *       console.log(`Position moved to breakeven at ${currentPrice}`);
+     *     }
+     *   }
+     * }
      * ```
      */
-    activateScheduled: (symbol: string, backtest: boolean, activateId?: string) => Promise<void>;
+    breakeven: (symbol: string, currentPrice: number, backtest: boolean) => Promise<boolean>;
     /**
-     * Closes the pending signal without stopping the strategy.
+     * Adds a new averaging entry to an open position (DCA — Dollar Cost Averaging).
      *
-     * Clears the pending signal (active position).
-     * Does NOT affect scheduled signals or strategy operation.
-     * Does NOT set stop flag - strategy can continue generating new signals.
+     * Appends currentPrice to the _entry array. The effective entry price used in all
+     * distance and PNL calculations becomes the simple arithmetic mean of all _entry prices.
+     * Original priceOpen is preserved unchanged for identity/audit purposes.
      *
-     * Use case: Close an active position that is no longer desired without stopping the entire strategy.
+     * Rejection rules (returns false without throwing):
+     * - LONG: currentPrice >= last entry price (must average down, not up or equal)
+     * - SHORT: currentPrice <= last entry price (must average down, not up or equal)
+     *
+     * Validations (throws):
+     * - No pending signal exists
+     * - currentPrice is not a positive finite number
      *
      * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+     * @param currentPrice - New entry price to add to the averaging history
      * @param backtest - Whether running in backtest mode
-     * @param closeId - Optional identifier for this close operation
-     * @returns Promise that resolves when pending signal is cleared
+     * @returns Promise<boolean> - true if entry added, false if rejected by direction check
+     */
+    averageBuy: (symbol: string, currentPrice: number, backtest: boolean) => Promise<boolean>;
+    /**
+     * Disposes the strategy instance and cleans up resources.
      *
-     * @example
-     * ```typescript
-     * // Close pending signal without stopping strategy
-     * await strategy.closePending("BTCUSDT", false, "user-close-123");
-     * // Strategy continues, can generate new signals
-     * ```
+     * Called when the strategy is being removed from cache or shut down.
+     * Invokes the onDispose callback to notify external systems.
+     *
+     * @returns Promise that resolves when disposal is complete
      */
-    closePending: (symbol: string, backtest: boolean, closeId?: string) => Promise<void>;
+    dispose: () => Promise<void>;
+}
+/**
+ * Unique strategy identifier.
+ */
+type StrategyName = 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]>;
+
+/**
+ * Single log entry stored in the log history.
+ */
+interface ILogEntry {
+    /** Unique entry identifier generated via randomString */
+    id: string;
+    /** Log level */
+    type: "log" | "debug" | "info" | "warn";
+    /** Unix timestamp in milliseconds when the entry was created */
+    timestamp: number;
+    /** Date taken from backtest context to improve user experience */
+    createdAt: string;
+    /** Optional method context associated with the log entry, providing additional details about the execution environment or state when the log was recorded */
+    methodContext: IMethodContext | null;
+    /** Optional execution context associated with the log entry, providing additional details about the execution environment or state when the log was recorded */
+    executionContext: IExecutionContext | null;
+    /** Log topic / method name */
+    topic: string;
+    /** Additional arguments passed to the log call */
+    args: unknown[];
+}
+/**
+ * Interface representing a logging mechanism for the swarm system.
+ * Provides methods to record messages at different severity levels, used across components like agents, sessions, states, storage, swarms, history, embeddings, completions, and policies.
+ * Logs are utilized to track lifecycle events (e.g., initialization, disposal), operational details (e.g., tool calls, message emissions), validation outcomes (e.g., policy checks), and errors (e.g., persistence failures), aiding in debugging, monitoring, and auditing.
+*/
+interface ILogger {
+    /**
+     * Logs a general-purpose message.
+     * Used throughout the swarm system to record significant events or state changes, such as agent execution, session connections, or storage updates.
+     */
+    log(topic: string, ...args: any[]): void;
+    /**
+     * Logs a debug-level message.
+     * Employed for detailed diagnostic information, such as intermediate states during agent tool calls, swarm navigation changes, or embedding creation processes, typically enabled in development or troubleshooting scenarios.
+     */
+    debug(topic: string, ...args: any[]): void;
+    /**
+     * Logs an info-level message.
+     * 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;
+}
+
+/**
+ * Candle time interval for fetching historical data.
+ */
+type CandleInterval = "1m" | "3m" | "5m" | "15m" | "30m" | "1h" | "2h" | "4h" | "6h" | "8h";
+/** Numeric type that can be undefined (used for optional numeric values) */
+type Num = number | undefined;
+interface IPublicCandleData {
+    /** Unix timestamp in milliseconds when candle opened */
+    timestamp: Num;
+    /** Opening price at candle start */
+    open: Num;
+    /** Highest price during candle period */
+    high: Num;
+    /** Lowest price during candle period */
+    low: Num;
+    /** Closing price at candle end */
+    close: Num;
+    /** Trading volume during candle period */
+    volume: Num;
+}
+/**
+ * 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;
+}
+/**
+ * Single bid or ask in order book.
+ */
+interface IBidData {
+    /** Price level as string */
+    price: string;
+    /** Quantity at this price level as string */
+    quantity: string;
+}
+/**
+ * Order book data containing bids and asks.
+ */
+interface IOrderBookData {
+    /** Trading pair symbol */
+    symbol: string;
+    /** Array of bid orders (buy orders) */
+    bids: IBidData[];
+    /** Array of ask orders (sell orders) */
+    asks: IBidData[];
+}
+/**
+ * Aggregated trade data point.
+ * Represents a single trade that has occurred, used for detailed analysis and backtesting.
+ * Includes price, quantity, timestamp, and whether the buyer is the market maker (which can indicate trade direction).
+ *
+ */
+interface IAggregatedTradeData {
+    /** Unique identifier for the aggregated trade */
+    id: string;
+    /** Price at which the trade occurred */
+    price: number;
+    /** Quantity traded */
+    qty: number;
+    /** Unix timestamp in milliseconds when the trade occurred */
+    timestamp: number;
+    /** Whether the buyer is the market maker (true if buyer is maker, false if seller is maker) */
+    isBuyerMaker: boolean;
+}
+/**
+ * Exchange parameters passed to ClientExchange constructor.
+ * Combines schema with runtime dependencies.
+ * Note: All exchange methods are required in params (defaults are applied during initialization).
+ */
+interface IExchangeParams extends IExchangeSchema {
+    /** Logger service for debug output */
+    logger: ILogger;
+    /** Execution context service (symbol, when, backtest flag) */
+    execution: TExecutionContextService;
+    /** Fetch candles from data source (required, defaults applied) */
+    getCandles: (symbol: string, interval: CandleInterval, since: Date, limit: number, backtest: boolean) => Promise<ICandleData[]>;
+    /** Format quantity according to exchange precision rules (required, defaults applied) */
+    formatQuantity: (symbol: string, quantity: number, backtest: boolean) => Promise<string>;
+    /** Format price according to exchange precision rules (required, defaults applied) */
+    formatPrice: (symbol: string, price: number, backtest: boolean) => Promise<string>;
+    /** Fetch order book for a trading pair (required, defaults applied) */
+    getOrderBook: (symbol: string, depth: number, from: Date, to: Date, backtest: boolean) => Promise<IOrderBookData>;
+    /** Fetch aggregated trades for a trading pair (required, defaults applied) */
+    getAggregatedTrades: (symbol: string, from: Date, to: Date, backtest: boolean) => Promise<IAggregatedTradeData[]>;
+}
+/**
+ * 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 | Promise<void>;
+}
+/**
+ * Exchange schema registered via addExchange().
+ * Defines candle data source and formatting logic.
+ */
+interface IExchangeSchema {
+    /** Unique exchange identifier for registration */
+    exchangeName: ExchangeName;
+    /** Optional developer note for documentation */
+    note?: string;
     /**
-     * Executes partial close at profit level (moving toward TP).
-     *
-     * Closes specified percentage of position at current price.
-     * Updates _tpClosed, _totalClosed, and _partialHistory state.
-     * Persists updated signal state for crash recovery.
-     *
-     * Validations:
-     * - Throws if no pending signal exists
-     * - Throws if called on scheduled signal (not yet activated)
-     * - Throws if percentToClose <= 0 or > 100
-     * - Returns false if _totalClosed + percentToClose > 100 (prevents over-closing)
-     *
-     * Use case: User-controlled partial close triggered from onPartialProfit callback.
+     * Fetch candles from data source (API or database).
      *
      * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
-     * @param percentToClose - Absolute percentage of position to close (0-100)
-     * @param currentPrice - Current market price for partial close
+     * @param interval - Candle time interval (e.g., "1m", "1h")
+     * @param since - Start date for candle fetching
+     * @param limit - Maximum number of candles to fetch
      * @param backtest - Whether running in backtest mode
-     * @returns Promise<boolean> - true if partial close executed, false if skipped
-     *
-     * @example
-     * ```typescript
-     * callbacks: {
-     *   onPartialProfit: async (symbol, signal, currentPrice, percentTp, backtest) => {
-     *     if (percentTp >= 50) {
-     *       const success = await strategy.partialProfit(symbol, 25, currentPrice, backtest);
-     *       if (success) {
-     *         console.log('Partial profit executed');
-     *       }
-     *     }
-     *   }
-     * }
-     * ```
+     * @returns Promise resolving to array of OHLCV candle data
      */
-    partialProfit: (symbol: string, percentToClose: number, currentPrice: number, backtest: boolean) => Promise<boolean>;
+    getCandles: (symbol: string, interval: CandleInterval, since: Date, limit: number, backtest: boolean) => Promise<IPublicCandleData[]>;
     /**
-     * Executes partial close at loss level (moving toward SL).
-     *
-     * Closes specified percentage of position at current price.
-     * Updates _slClosed, _totalClosed, and _partialHistory state.
-     * Persists updated signal state for crash recovery.
-     *
-     * Validations:
-     * - Throws if no pending signal exists
-     * - Throws if called on scheduled signal (not yet activated)
-     * - Throws if percentToClose <= 0 or > 100
-     * - Returns false if _totalClosed + percentToClose > 100 (prevents over-closing)
+     * Format quantity according to exchange precision rules.
      *
-     * Use case: User-controlled partial close triggered from onPartialLoss callback.
+     * Optional. If not provided, defaults to Bitcoin precision on Binance (8 decimal places).
      *
-     * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
-     * @param percentToClose - Absolute percentage of position to close (0-100)
-     * @param currentPrice - Current market price for partial close
+     * @param symbol - Trading pair symbol
+     * @param quantity - Raw quantity value
      * @param backtest - Whether running in backtest mode
-     * @returns Promise<boolean> - true if partial close executed, false if skipped
-     *
-     * @example
-     * ```typescript
-     * callbacks: {
-     *   onPartialLoss: async (symbol, signal, currentPrice, percentSl, backtest) => {
-     *     if (percentSl >= 80) {
-     *       const success = await strategy.partialLoss(symbol, 50, currentPrice, backtest);
-     *       if (success) {
-     *         console.log('Partial loss executed');
-     *       }
-     *     }
-     *   }
-     * }
-     * ```
+     * @returns Promise resolving to formatted quantity string
      */
-    partialLoss: (symbol: string, percentToClose: number, currentPrice: number, backtest: boolean) => Promise<boolean>;
+    formatQuantity?: (symbol: string, quantity: number, backtest: boolean) => Promise<string>;
     /**
-     * Adjusts trailing stop-loss by shifting distance between entry and original SL.
-     *
-     * CRITICAL: Always calculates from ORIGINAL SL, not from current trailing SL.
-     * This prevents error accumulation on repeated calls.
-     * Larger percentShift ABSORBS smaller one (updates only towards better protection).
-     *
-     * Calculates new SL based on percentage shift of the ORIGINAL distance (entry - originalSL):
-     * - Negative %: tightens stop (moves SL closer to entry, reduces risk)
-     * - Positive %: loosens stop (moves SL away from entry, allows more drawdown)
-     *
-     * For LONG position (entry=100, originalSL=90, distance=10%):
-     * - percentShift = -50: newSL = 100 - 10%*(1-0.5) = 95 (5% distance, tighter)
-     * - percentShift = +20: newSL = 100 - 10%*(1+0.2) = 88 (12% distance, looser)
-     *
-     * For SHORT position (entry=100, originalSL=110, distance=10%):
-     * - percentShift = -50: newSL = 100 + 10%*(1-0.5) = 105 (5% distance, tighter)
-     * - percentShift = +20: newSL = 100 + 10%*(1+0.2) = 112 (12% distance, looser)
+     * Format price according to exchange precision rules.
      *
-     * Absorption behavior:
-     * - First call: sets trailing SL unconditionally
-     * - Subsequent calls: updates only if new SL is BETTER (protects more profit)
-     * - For LONG: only accepts HIGHER SL (never moves down, closer to entry wins)
-     * - For SHORT: only accepts LOWER SL (never moves up, closer to entry wins)
-     * - Stores in _trailingPriceStopLoss, original priceStopLoss always preserved
+     * Optional. If not provided, defaults to Bitcoin precision on Binance (2 decimal places).
      *
-     * Validations:
-     * - Throws if no pending signal exists
-     * - Throws if percentShift < -100 or > 100
-     * - Throws if percentShift === 0
-     * - Skips if new SL would cross entry price
-     * - Skips if currentPrice already crossed new SL level (price intrusion protection)
+     * @param symbol - Trading pair symbol
+     * @param price - Raw price value
+     * @param backtest - Whether running in backtest mode
+     * @returns Promise resolving to formatted price string
+     */
+    formatPrice?: (symbol: string, price: number, backtest: boolean) => Promise<string>;
+    /**
+     * Fetch order book for a trading pair.
      *
-     * Use case: User-controlled trailing stop triggered from onPartialProfit callback.
+     * Optional. If not provided, throws an error when called.
      *
      * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
-     * @param percentShift - Percentage shift of ORIGINAL SL distance [-100, 100], excluding 0
-     * @param currentPrice - Current market price to check for intrusion
+     * @param depth - Maximum depth levels for both bids and asks (default: CC_ORDER_BOOK_MAX_DEPTH_LEVELS)
+     * @param from - Start of time range (used in backtest for historical data, can be ignored in live)
+     * @param to - End of time range (used in backtest for historical data, can be ignored in live)
      * @param backtest - Whether running in backtest mode
-     * @returns Promise<boolean> - true if trailing SL was set/updated, false if rejected
+     * @returns Promise resolving to order book data
      *
      * @example
      * ```typescript
-     * callbacks: {
-     *   onPartialProfit: async (symbol, signal, currentPrice, percentTp, backtest) => {
-     *     if (percentTp >= 50) {
-     *       // LONG: entry=100, originalSL=90, distance=10%
-     *
-     *       // First call: tighten by 5%
-     *       const success1 = await strategy.trailingStop(symbol, -5, currentPrice, backtest);
-     *       // success1 = true, newDistance = 10% - 5% = 5%, newSL = 95
-     *
-     *       // Second call: try weaker protection
-     *       const success2 = await strategy.trailingStop(symbol, -3, currentPrice, backtest);
-     *       // success2 = false (SKIPPED: newSL=97 < 95, worse protection, larger % absorbs smaller)
-     *
-     *       // Third call: stronger protection
-     *       const success3 = await strategy.trailingStop(symbol, -7, currentPrice, backtest);
-     *       // success3 = true (ACCEPTED: newDistance = 3%, newSL = 97 > 95, better protection)
-     *     }
+     * // Backtest implementation: returns historical order book for the time range
+     * const backtestOrderBook = async (symbol: string, depth: number, from: Date, to: Date, backtest: boolean) => {
+     *   if (backtest) {
+     *     return await database.getOrderBookSnapshot(symbol, depth, from, to);
      *   }
-     * }
+     *   return await exchange.fetchOrderBook(symbol, depth);
+     * };
+     *
+     * // Live implementation: ignores from/to when not in backtest mode
+     * const liveOrderBook = async (symbol: string, depth: number, _from: Date, _to: Date, backtest: boolean) => {
+     *   return await exchange.fetchOrderBook(symbol, depth);
+     * };
      * ```
      */
-    trailingStop: (symbol: string, percentShift: number, currentPrice: number, backtest: boolean) => Promise<boolean>;
+    getOrderBook?: (symbol: string, depth: number, from: Date, to: Date, backtest: boolean) => Promise<IOrderBookData>;
     /**
-     * Adjusts the trailing take-profit distance for an active pending signal.
-     *
-     * CRITICAL: Always calculates from ORIGINAL TP, not from current trailing TP.
-     * This prevents error accumulation on repeated calls.
-     * Larger percentShift ABSORBS smaller one (updates only towards more conservative TP).
-     *
-     * Updates the take-profit distance by a percentage adjustment relative to the ORIGINAL TP distance.
-     * Negative percentShift brings TP closer to entry (more conservative).
-     * Positive percentShift moves TP further from entry (more aggressive).
-     *
-     * Absorption behavior:
-     * - First call: sets trailing TP unconditionally
-     * - Subsequent calls: updates only if new TP is MORE CONSERVATIVE (closer to entry)
-     * - For LONG: only accepts LOWER TP (never moves up, closer to entry wins)
-     * - For SHORT: only accepts HIGHER TP (never moves down, closer to entry wins)
-     * - Stores in _trailingPriceTakeProfit, original priceTakeProfit always preserved
-     *
-     * Price intrusion protection: If current price has already crossed the new TP level,
-     * the update is skipped to prevent immediate TP triggering.
-     *
-     * @param symbol - Trading pair symbol
-     * @param percentShift - Percentage adjustment to ORIGINAL TP distance (-100 to 100)
-     * @param currentPrice - Current market price to check for intrusion
+     * Fetch aggregated trades for a trading pair.
+     * Optional. If not provided, throws an error when called.
+     * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+     * @param from - Start of time range (used in backtest for historical data, can be ignored in live)
+     * @param to - End of time range (used in backtest for historical data, can be ignored in live)
      * @param backtest - Whether running in backtest mode
-     * @returns Promise<boolean> - true if trailing TP was set/updated, false if rejected
-     *
+     * @return Promise resolving to array of aggregated trade data
      * @example
      * ```typescript
-     * callbacks: {
-     *   onPartialProfit: async (symbol, signal, currentPrice, percentTp, backtest) => {
-     *     // LONG: entry=100, originalTP=110, distance=10%, currentPrice=102
-     *
-     *     // First call: bring TP closer by 3%
-     *     const success1 = await strategy.trailingTake(symbol, -3, currentPrice, backtest);
-     *     // success1 = true, newDistance = 10% - 3% = 7%, newTP = 107
-     *
-     *     // Second call: try to move TP further (less conservative)
-     *     const success2 = await strategy.trailingTake(symbol, 2, currentPrice, backtest);
-     *     // success2 = false (SKIPPED: newTP=112 > 107, less conservative, larger % absorbs smaller)
-     *
-     *     // Third call: even more conservative
-     *     const success3 = await strategy.trailingTake(symbol, -5, currentPrice, backtest);
-     *     // success3 = true (ACCEPTED: newDistance = 5%, newTP = 105 < 107, more conservative)
+     * // Backtest implementation: returns historical aggregated trades for the time range
+     * const backtestAggregatedTrades = async (symbol: string, from: Date, to: Date, backtest: boolean) => {
+     *   if (backtest) {
+     *     return await database.getAggregatedTrades(symbol, from, to);
      *   }
-     * }
+     *   return await exchange.fetchAggregatedTrades(symbol);
+     * };
+     *
+     * // Live implementation: ignores from/to when not in backtest mode
+     * const liveAggregatedTrades = async (symbol: string, _from: Date, _to: Date, backtest: boolean) => {
+     *   return await exchange.fetchAggregatedTrades(symbol);
+     * };
      * ```
      */
-    trailingTake: (symbol: string, percentShift: number, currentPrice: number, backtest: boolean) => Promise<boolean>;
+    getAggregatedTrades?: (symbol: string, from: Date, to: Date, backtest: boolean) => Promise<IAggregatedTradeData[]>;
+    /** Optional lifecycle event callbacks (onCandleData) */
+    callbacks?: Partial<IExchangeCallbacks>;
+}
+/**
+ * Exchange interface implemented by ClientExchange.
+ * Provides candle data access and VWAP calculation.
+ */
+interface IExchange {
     /**
-     * Moves stop-loss to breakeven (entry price) when price reaches threshold.
-     *
-     * Moves SL to entry price (zero-risk position) when current price has moved
-     * far enough in profit direction to cover transaction costs (slippage + fees).
-     * Threshold is calculated as: (CC_PERCENT_SLIPPAGE + CC_PERCENT_FEE) * 2
-     *
-     * Behavior:
-     * - Returns true if SL was moved to breakeven
-     * - Returns false if conditions not met (threshold not reached or already at breakeven)
-     * - Uses _trailingPriceStopLoss to store breakeven SL (preserves original priceStopLoss)
-     * - Only moves SL once per position (idempotent - safe to call multiple times)
-     *
-     * For LONG position (entry=100, slippage=0.1%, fee=0.1%):
-     * - Threshold: (0.1 + 0.1) * 2 = 0.4%
-     * - Breakeven available when price >= 100.4 (entry + 0.4%)
-     * - Moves SL from original (e.g. 95) to 100 (breakeven)
-     * - Returns true on first successful move, false on subsequent calls
-     *
-     * For SHORT position (entry=100, slippage=0.1%, fee=0.1%):
-     * - Threshold: (0.1 + 0.1) * 2 = 0.4%
-     * - Breakeven available when price <= 99.6 (entry - 0.4%)
-     * - Moves SL from original (e.g. 105) to 100 (breakeven)
-     * - Returns true on first successful move, false on subsequent calls
-     *
-     * Validations:
-     * - Throws if no pending signal exists
-     * - Throws if currentPrice is not a positive finite number
+     * Fetch historical candles backwards from execution context time.
      *
-     * Use case: User-controlled breakeven protection triggered from onPartialProfit callback.
+     * @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 currentPrice - Current market price to check threshold
-     * @param backtest - Whether running in backtest mode
-     * @returns Promise<boolean> - true if breakeven was set, false if conditions not met
+     * @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.
      *
-     * @example
-     * ```typescript
-     * callbacks: {
-     *   onPartialProfit: async (symbol, signal, currentPrice, percentTp, backtest) => {
-     *     // Try to move SL to breakeven when threshold reached
-     *     const movedToBreakeven = await strategy.breakeven(symbol, currentPrice, backtest);
-     *     if (movedToBreakeven) {
-     *       console.log(`Position moved to breakeven at ${currentPrice}`);
-     *     }
-     *   }
-     * }
-     * ```
+     * @param symbol - Trading pair symbol
+     * @param quantity - Raw quantity value
+     * @returns Promise resolving to formatted quantity string
      */
-    breakeven: (symbol: string, currentPrice: number, backtest: boolean) => Promise<boolean>;
+    formatQuantity: (symbol: string, quantity: number) => Promise<string>;
     /**
-     * Adds a new averaging entry to an open position (DCA — Dollar Cost Averaging).
+     * Format price for exchange precision.
      *
-     * Appends currentPrice to the _entry array. The effective entry price used in all
-     * distance and PNL calculations becomes the simple arithmetic mean of all _entry prices.
-     * Original priceOpen is preserved unchanged for identity/audit purposes.
+     * @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.
      *
-     * Rejection rules (returns false without throwing):
-     * - LONG: currentPrice >= last entry price (must average down, not up or equal)
-     * - SHORT: currentPrice <= last entry price (must average down, not up or equal)
+     * Formula: VWAP = Σ(Typical Price × Volume) / Σ(Volume)
+     * where Typical Price = (High + Low + Close) / 3
      *
-     * Validations (throws):
-     * - No pending signal exists
-     * - currentPrice is not a positive finite number
+     * @param symbol - Trading pair symbol
+     * @returns Promise resolving to volume-weighted average price
+     */
+    getAveragePrice: (symbol: string) => Promise<number>;
+    /**
+     * Fetch order book for a trading pair.
      *
      * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
-     * @param currentPrice - New entry price to add to the averaging history
-     * @param backtest - Whether running in backtest mode
-     * @returns Promise<boolean> - true if entry added, false if rejected by direction check
+     * @param depth - Maximum depth levels (default: CC_ORDER_BOOK_MAX_DEPTH_LEVELS)
+     * @returns Promise resolving to order book data
      */
-    averageBuy: (symbol: string, currentPrice: number, backtest: boolean) => Promise<boolean>;
+    getOrderBook: (symbol: string, depth?: number) => Promise<IOrderBookData>;
     /**
-     * Disposes the strategy instance and cleans up resources.
+     * Fetch aggregated trades for a trading pair.
      *
-     * Called when the strategy is being removed from cache or shut down.
-     * Invokes the onDispose callback to notify external systems.
+     * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+     * @param limit - Optional maximum number of aggregated trades to fetch. If empty returns one hour of data.
+     * @returns Promise resolving to array of aggregated trade data
+     */
+    getAggregatedTrades: (symbol: string, limit?: number) => Promise<IAggregatedTradeData[]>;
+    /**
+     * Fetch raw candles with flexible date/limit parameters.
      *
-     * @returns Promise that resolves when disposal is complete
+     * All modes respect execution context and prevent look-ahead bias.
+     *
+     * Parameter combinations:
+     * 1. sDate + eDate + limit: fetches with explicit parameters, validates eDate <= when
+     * 2. sDate + eDate: calculates limit from date range, validates eDate <= when
+     * 3. eDate + limit: calculates sDate backward, validates eDate <= when
+     * 4. sDate + limit: fetches forward, validates calculated endTimestamp <= when
+     * 5. Only limit: uses execution.context.when as reference (backward)
+     *
+     * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+     * @param interval - Candle interval (e.g., "1m", "1h")
+     * @param limit - Optional number of candles to fetch
+     * @param sDate - Optional start date in milliseconds
+     * @param eDate - Optional end date in milliseconds
+     * @returns Promise resolving to array of candles
      */
-    dispose: () => Promise<void>;
+    getRawCandles: (symbol: string, interval: CandleInterval, limit?: number, sDate?: number, eDate?: number) => Promise<ICandleData[]>;
 }
 /**
- * Unique strategy identifier.
+ * Unique exchange identifier.
  */
-type StrategyName = string;
+type ExchangeName = string;
+
+/**
+ * Parameters for pre-caching candles into persist storage.
+ * Used to download historical candle data before running a backtest.
+ */
+interface ICacheCandlesParams {
+    /** Trading pair symbol (e.g., "BTCUSDT") */
+    symbol: string;
+    /** Name of the registered exchange schema */
+    exchangeName: ExchangeName;
+    /** Candle time interval (e.g., "1m", "4h") */
+    interval: CandleInterval;
+    /** Start date of the caching range (inclusive) */
+    from: Date;
+    /** End date of the caching range (inclusive) */
+    to: Date;
+}
+/**
+ * Parameters for validating cached candle timestamps.
+ * Reads JSON files directly from persist storage directory.
+ */
+interface ICheckCandlesParams {
+    /** Trading pair symbol (e.g., "BTCUSDT") */
+    symbol: string;
+    /** Name of the registered exchange schema */
+    exchangeName: ExchangeName;
+    /** Candle time interval (e.g., "1m", "4h") */
+    interval: CandleInterval;
+    /** Start date of the validation range (inclusive) */
+    from: Date;
+    /** End date of the validation range (inclusive) */
+    to: Date;
+    /** Base directory of candle persist storage (default: "./dump/data/candle") */
+    baseDir?: string;
+}
+/**
+ * Checks cached candle timestamps for correct interval alignment.
+ * Reads JSON files directly from persist storage without using abstractions.
+ *
+ * @param params - Validation parameters
+ */
+declare function checkCandles(params: ICheckCandlesParams): Promise<void>;
+/**
+ * Pre-caches candles for a date range into persist storage.
+ * Downloads all candles matching the interval from `from` to `to`.
+ *
+ * @param params - Cache parameters
+ */
+declare function warmCandles(params: ICacheCandlesParams): Promise<void>;
+
+/**
+ * Type alias for enum objects with string key-value pairs
+ */
+type Enum = Record<string, string>;
+/**
+ * Type alias for ValidateArgs with any enum type
+ */
+type Args = ValidateArgs<any>;
+/**
+ * Interface defining validation arguments for all entity types.
+ *
+ * Each property accepts an enum object where values will be validated
+ * against registered entities in their respective validation services.
+ *
+ * @template T - Enum type extending Record<string, string>
+ */
+interface ValidateArgs<T = Enum> {
+    /**
+     * Exchange name enum to validate
+     * @example { BINANCE: "binance", BYBIT: "bybit" }
+     */
+    ExchangeName?: T;
+    /**
+     * Frame (timeframe) name enum to validate
+     * @example { Q1_2024: "2024-Q1", Q2_2024: "2024-Q2" }
+     */
+    FrameName?: T;
+    /**
+     * Strategy name enum to validate
+     * @example { MOMENTUM_BTC: "momentum-btc" }
+     */
+    StrategyName?: T;
+    /**
+     * Risk profile name enum to validate
+     * @example { CONSERVATIVE: "conservative", AGGRESSIVE: "aggressive" }
+     */
+    RiskName?: T;
+    /**
+     * Action handler name enum to validate
+     * @example { TELEGRAM_NOTIFIER: "telegram-notifier" }
+     */
+    ActionName?: T;
+    /**
+     * Sizing strategy name enum to validate
+     * @example { FIXED_1000: "fixed-1000" }
+     */
+    SizingName?: T;
+    /**
+     * Walker (parameter sweep) name enum to validate
+     * @example { RSI_SWEEP: "rsi-sweep" }
+     */
+    WalkerName?: T;
+}
+/**
+ * Validates the existence of all provided entity names across validation services.
+ *
+ * This function accepts enum objects for various entity types (exchanges, frames,
+ * strategies, risks, sizings, walkers) and validates that each entity
+ * name exists in its respective registry. Validation results are memoized for performance.
+ *
+ * If no arguments are provided (or specific entity types are omitted), the function
+ * automatically fetches and validates ALL registered entities from their respective
+ * validation services. This is useful for comprehensive validation of the entire setup.
+ *
+ * Use this before running backtests or optimizations to ensure all referenced
+ * entities are properly registered and configured.
+ *
+ * @public
+ * @param args - Partial validation arguments containing entity name enums to validate.
+ *                If empty or omitted, validates all registered entities.
+ * @throws {Error} If any entity name is not found in its validation service
+ *
+ * @example
+ * ```typescript
+ * // Validate ALL registered entities (exchanges, frames, strategies, etc.)
+ * await validate({});
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Define your entity name enums
+ * enum ExchangeName {
+ *   BINANCE = "binance",
+ *   BYBIT = "bybit"
+ * }
+ *
+ * enum StrategyName {
+ *   MOMENTUM_BTC = "momentum-btc"
+ * }
+ *
+ * // Validate specific entities before running backtest
+ * await validate({
+ *   ExchangeName,
+ *   StrategyName,
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Validate specific entity types
+ * await validate({
+ *   RiskName: { CONSERVATIVE: "conservative" },
+ *   SizingName: { FIXED_1000: "fixed-1000" },
+ * });
+ * ```
+ */
+declare function validate(args?: Partial<Args>): Promise<void>;
 
 /**
  * Statistical data calculated from backtest results.
@@ -9995,6 +9999,15 @@ declare class LogAdapter implements ILog {
      * All future log writes will be no-ops.
      */
     useDummy: () => void;
+    /**
+     * Switches to JSONL file log adapter.
+     * Log entries will be appended to {dirName}/{fileName}.jsonl.
+     * Reads are performed by parsing all lines from the file.
+     *
+     * @param fileName - Base file name without extension (default: "log")
+     * @param dirName - Directory for the JSONL file (default: ./dump/log)
+     */
+    useJsonl: (fileName?: string, dirName?: string) => void;
 }
 /**
  * Global singleton instance of LogAdapter.