backtest-kit 6.10.0 → 6.12.0

package/types.d.ts

@@ -1900,6 +1900,8 @@ interface SignalCommitBase {
     totalPartials: number;
     /** Original entry price at signal creation (unchanged by DCA averaging). */
     originalPriceOpen: number;
+    /** Optional human-readable description of signal reason */
+    note?: string;
 }
 /**
  * Cancel scheduled signal event.
@@ -2142,6 +2144,16 @@ interface ActivateScheduledCommit extends SignalCommitBase {
  */
 type StrategyCommitContract = CancelScheduledCommit | ClosePendingCommit | PartialProfitCommit | PartialLossCommit | TrailingStopCommit | TrailingTakeCommit | BreakevenCommit | AverageBuyCommit | ActivateScheduledCommit;
 
+/**
+ * Commit payload for strategy commits.
+ * Used in activateScheduled, closePending, cancelScheduled
+ */
+type CommitPayload = {
+    /** Commit id */
+    id: string;
+    /** Note describing the commit */
+    note: string;
+};
 /**
  * Signal generation interval for throttling.
  * Enforces minimum time between getSignal calls.
@@ -2443,6 +2455,8 @@ interface IRiskSignalRow extends IPublicSignalRow {
 interface IScheduledSignalCancelRow extends IScheduledSignalRow {
     /** Cancellation ID (only for user-initiated cancellations) */
     cancelId?: string;
+    /** Note from user payload (only for user-initiated cancellations) */
+    cancelNote?: string;
 }
 /**
  * Base interface for queued commit events.
@@ -2577,14 +2591,18 @@ interface IStrategySchema {
     strategyName: StrategyName;
     /** Optional developer note for documentation */
     note?: string;
-    /** Minimum interval between getSignal calls (throttling) */
-    interval: SignalInterval;
+    /**
+     * Minimum interval between getSignal calls (throttling)
+     *
+     * Default: 1m
+     */
+    interval?: SignalInterval;
     /**
      * Signal generation function (returns null if no signal, validated DTO if signal).
      * If priceOpen is provided - becomes scheduled signal waiting for price to reach entry point.
      * If priceOpen is omitted - opens immediately at current price.
      */
-    getSignal: (symbol: string, when: Date) => Promise<ISignalDto | null>;
+    getSignal: (symbol: string, when: Date, currentPrice: number) => Promise<ISignalDto | null>;
     /** Optional lifecycle event callbacks (onOpen, onClose) */
     callbacks?: Partial<IStrategyCallbacks>;
     /** Optional risk profile identifier for risk management */
@@ -3046,7 +3064,7 @@ interface IStrategy {
      * // Strategy continues, can generate new signals
      * ```
      */
-    cancelScheduled: (symbol: string, backtest: boolean, cancelId?: string) => Promise<void>;
+    cancelScheduled: (symbol: string, backtest: boolean, payload: Partial<CommitPayload>) => Promise<void>;
     /**
      * Activates the scheduled signal without waiting for price to reach priceOpen.
      *
@@ -3068,7 +3086,7 @@ interface IStrategy {
      * // Scheduled signal becomes pending signal immediately
      * ```
      */
-    activateScheduled: (symbol: string, backtest: boolean, activateId?: string) => Promise<void>;
+    activateScheduled: (symbol: string, backtest: boolean, payload: Partial<CommitPayload>) => Promise<void>;
     /**
      * Closes the pending signal without stopping the strategy.
      *
@@ -3090,7 +3108,7 @@ interface IStrategy {
      * // Strategy continues, can generate new signals
      * ```
      */
-    closePending: (symbol: string, backtest: boolean, closeId?: string) => Promise<void>;
+    closePending: (symbol: string, backtest: boolean, payload: Partial<CommitPayload>) => Promise<void>;
     /**
      * Executes partial close at profit level (moving toward TP).
      *
@@ -3670,6 +3688,26 @@ interface IStrategy {
      * @returns Promise resolving to recovery distance in PnL cost (≥ 0) or null
      */
     getPositionHighestMaxDrawdownPnlCost: (symbol: string, currentPrice: number) => Promise<number | null>;
+    /**
+     * Returns the peak-to-trough PnL percentage distance between the position's highest profit and deepest drawdown.
+     *
+     * Computed as: max(0, peakPnlPercentage - fallPnlPercentage).
+     *
+     * @param symbol - Trading pair symbol
+     * @param currentPrice - Current market price
+     * @returns Promise resolving to peak-to-trough PnL percentage distance (≥ 0) or null
+     */
+    getMaxDrawdownDistancePnlPercentage: (symbol: string, currentPrice: number) => Promise<number | null>;
+    /**
+     * Returns the peak-to-trough PnL cost distance between the position's highest profit and deepest drawdown.
+     *
+     * Computed as: max(0, peakPnlCost - fallPnlCost).
+     *
+     * @param symbol - Trading pair symbol
+     * @param currentPrice - Current market price
+     * @returns Promise resolving to peak-to-trough PnL cost distance (≥ 0) or null
+     */
+    getMaxDrawdownDistancePnlCost: (symbol: string, currentPrice: number) => Promise<number | null>;
     /**
      * Disposes the strategy instance and cleans up resources.
      *
@@ -4721,7 +4759,7 @@ interface IPositionOverlapLadder {
  *
  * @param symbol - Trading pair symbol
  * @param strategyName - Strategy name
- * @param cancelId - Optional cancellation ID for tracking user-initiated cancellations
+ * @param payload - Optional commit payload with id and note
  * @returns Promise that resolves when scheduled signal is cancelled
  *
  * @example
@@ -4729,10 +4767,10 @@ interface IPositionOverlapLadder {
  * import { commitCancelScheduled } from "backtest-kit";
  *
  * // Cancel scheduled signal with custom ID
- * await commitCancelScheduled("BTCUSDT", "manual-cancel-001");
+ * await commitCancelScheduled("BTCUSDT", { id: "manual-cancel-001" });
  * ```
  */
-declare function commitCancelScheduled(symbol: string, cancelId?: string): Promise<void>;
+declare function commitCancelScheduled(symbol: string, payload?: Partial<CommitPayload>): Promise<void>;
 /**
  * Closes the pending signal without stopping the strategy.
  *
@@ -4743,7 +4781,7 @@ declare function commitCancelScheduled(symbol: string, cancelId?: string): Promi
  * Automatically detects backtest/live mode from execution context.
  *
  * @param symbol - Trading pair symbol
- * @param closeId - Optional close ID for tracking user-initiated closes
+ * @param payload - Optional commit payload with id and note
  * @returns Promise that resolves when pending signal is closed
  *
  * @example
@@ -4751,10 +4789,10 @@ declare function commitCancelScheduled(symbol: string, cancelId?: string): Promi
  * import { commitClosePending } from "backtest-kit";
  *
  * // Close pending signal with custom ID
- * await commitClosePending("BTCUSDT", "manual-close-001");
+ * await commitClosePending("BTCUSDT", { id: "manual-close-001" });
  * ```
  */
-declare function commitClosePending(symbol: string, closeId?: string): Promise<void>;
+declare function commitClosePending(symbol: string, payload?: Partial<CommitPayload>): Promise<void>;
 /**
  * Executes partial close at profit level (moving toward TP).
  *
@@ -4962,7 +5000,7 @@ declare function commitBreakeven(symbol: string): Promise<boolean>;
  * Automatically detects backtest/live mode from execution context.
  *
  * @param symbol - Trading pair symbol
- * @param activateId - Optional activation ID for tracking user-initiated activations
+ * @param payload - Optional commit payload with id and note
  * @returns Promise that resolves when activation flag is set
  *
  * @example
@@ -4970,10 +5008,10 @@ declare function commitBreakeven(symbol: string): Promise<boolean>;
  * import { commitActivateScheduled } from "backtest-kit";
  *
  * // Activate scheduled signal early with custom ID
- * await commitActivateScheduled("BTCUSDT", "manual-activate-001");
+ * await commitActivateScheduled("BTCUSDT", { id: "manual-activate-001" });
  * ```
  */
-declare function commitActivateScheduled(symbol: string, activateId?: string): Promise<void>;
+declare function commitActivateScheduled(symbol: string, payload?: Partial<CommitPayload>): Promise<void>;
 /**
  * Adds a new DCA entry to the active pending signal.
  *
@@ -5702,6 +5740,42 @@ declare function getPositionHighestMaxDrawdownPnlPercentage(symbol: string): Pro
  * ```
  */
 declare function getPositionHighestMaxDrawdownPnlCost(symbol: string): Promise<number>;
+/**
+ * Returns the peak-to-trough PnL percentage distance between the position's highest profit and deepest drawdown.
+ *
+ * Computed as: max(0, peakPnlPercentage - fallPnlPercentage).
+ * Returns null if no pending signal exists.
+ *
+ * @param symbol - Trading pair symbol
+ * @returns Promise resolving to peak-to-trough PnL percentage distance (≥ 0) or null
+ *
+ * @example
+ * ```typescript
+ * import { getMaxDrawdownDistancePnlPercentage } from "backtest-kit";
+ *
+ * const dist = await getMaxDrawdownDistancePnlPercentage("BTCUSDT");
+ * // e.g. 3.5 (peak was +3.5% above trough)
+ * ```
+ */
+declare function getMaxDrawdownDistancePnlPercentage(symbol: string): Promise<number>;
+/**
+ * Returns the peak-to-trough PnL cost distance between the position's highest profit and deepest drawdown.
+ *
+ * Computed as: max(0, peakPnlCost - fallPnlCost).
+ * Returns null if no pending signal exists.
+ *
+ * @param symbol - Trading pair symbol
+ * @returns Promise resolving to peak-to-trough PnL cost distance (≥ 0) or null
+ *
+ * @example
+ * ```typescript
+ * import { getMaxDrawdownDistancePnlCost } from "backtest-kit";
+ *
+ * const dist = await getMaxDrawdownDistancePnlCost("BTCUSDT");
+ * // e.g. 7.2 (peak was $7.2 above trough)
+ * ```
+ */
+declare function getMaxDrawdownDistancePnlCost(symbol: string): Promise<number>;
 /**
  * Checks whether the current price falls within the tolerance zone of any existing DCA entry level.
  * Use this to prevent duplicate DCA entries at the same price area.
@@ -9173,7 +9247,7 @@ interface IRunContext extends IMethodContext, IExecutionContext {
  *
  * @template T - Return type of the function.
  */
-type Function$1<T extends unknown = any> = () => T | Promise<T>;
+type Function$2<T extends unknown = any> = () => T | Promise<T>;
 /**
  * Runs a function inside a mock method and execution context.
  *
@@ -9201,7 +9275,7 @@ type Function$1<T extends unknown = any> = () => T | Promise<T>;
  * );
  * ```
  */
-declare function runInMockContext<T extends unknown = any>(run: Function$1<T>, { exchangeName, frameName, strategyName, symbol, backtest: isBacktest, when, }: Partial<IRunContext>): Promise<T>;
+declare function runInMockContext<T extends unknown = any>(run: Function$2<T>, { exchangeName, frameName, strategyName, symbol, backtest: isBacktest, when, }: Partial<IRunContext>): Promise<T>;
 
 /**
  * Portfolio heatmap statistics for a single symbol.
@@ -9465,6 +9539,8 @@ interface PartialProfitAvailableNotification {
     pnlCost: number;
     /** Total invested capital in USD */
     pnlEntries: number;
+    /** Optional human-readable description of signal reason */
+    note?: string;
     /** Signal creation timestamp in milliseconds (when signal was first created/scheduled) */
     scheduledAt: number;
     /** Pending timestamp in milliseconds (when position became pending/active at priceOpen) */
@@ -9527,6 +9603,8 @@ interface PartialLossAvailableNotification {
     pnlCost: number;
     /** Total invested capital in USD */
     pnlEntries: number;
+    /** Optional human-readable description of signal reason */
+    note?: string;
     /** Signal creation timestamp in milliseconds (when signal was first created/scheduled) */
     scheduledAt: number;
     /** Pending timestamp in milliseconds (when position became pending/active at priceOpen) */
@@ -9587,6 +9665,8 @@ interface BreakevenAvailableNotification {
     pnlCost: number;
     /** Total invested capital in USD */
     pnlEntries: number;
+    /** Optional human-readable description of signal reason */
+    note?: string;
     /** Signal creation timestamp in milliseconds (when signal was first created/scheduled) */
     scheduledAt: number;
     /** Pending timestamp in milliseconds (when position became pending/active at priceOpen) */
@@ -9649,6 +9729,8 @@ interface PartialProfitCommitNotification {
     pnlCost: number;
     /** Total invested capital in USD */
     pnlEntries: number;
+    /** Optional human-readable description of signal reason */
+    note?: string;
     /** Signal creation timestamp in milliseconds (when signal was first created/scheduled) */
     scheduledAt: number;
     /** Pending timestamp in milliseconds (when position became pending/active at priceOpen) */
@@ -9711,6 +9793,8 @@ interface PartialLossCommitNotification {
     pnlCost: number;
     /** Total invested capital in USD */
     pnlEntries: number;
+    /** Optional human-readable description of signal reason */
+    note?: string;
     /** Signal creation timestamp in milliseconds (when signal was first created/scheduled) */
     scheduledAt: number;
     /** Pending timestamp in milliseconds (when position became pending/active at priceOpen) */
@@ -9771,6 +9855,8 @@ interface BreakevenCommitNotification {
     pnlCost: number;
     /** Total invested capital in USD */
     pnlEntries: number;
+    /** Optional human-readable description of signal reason */
+    note?: string;
     /** Signal creation timestamp in milliseconds (when signal was first created/scheduled) */
     scheduledAt: number;
     /** Pending timestamp in milliseconds (when position became pending/active at priceOpen) */
@@ -9835,6 +9921,8 @@ interface AverageBuyCommitNotification {
     pnlCost: number;
     /** Total invested capital in USD */
     pnlEntries: number;
+    /** Optional human-readable description of signal reason */
+    note?: string;
     /** Signal creation timestamp in milliseconds (when signal was first created/scheduled) */
     scheduledAt: number;
     /** Pending timestamp in milliseconds (when position became pending/active at priceOpen) */
@@ -9901,6 +9989,8 @@ interface ActivateScheduledCommitNotification {
     pendingAt: number;
     /** Current market price when activation was executed */
     currentPrice: number;
+    /** Optional human-readable description of signal reason */
+    note?: string;
     /** Unix timestamp in milliseconds when the notification was created */
     createdAt: number;
 }
@@ -9959,6 +10049,8 @@ interface TrailingStopCommitNotification {
     pnlCost: number;
     /** Total invested capital in USD */
     pnlEntries: number;
+    /** Optional human-readable description of signal reason */
+    note?: string;
     /** Signal creation timestamp in milliseconds (when signal was first created/scheduled) */
     scheduledAt: number;
     /** Pending timestamp in milliseconds (when position became pending/active at priceOpen) */
@@ -10021,6 +10113,8 @@ interface TrailingTakeCommitNotification {
     pnlCost: number;
     /** Total invested capital in USD */
     pnlEntries: number;
+    /** Optional human-readable description of signal reason */
+    note?: string;
     /** Signal creation timestamp in milliseconds (when signal was first created/scheduled) */
     scheduledAt: number;
     /** Pending timestamp in milliseconds (when position became pending/active at priceOpen) */
@@ -10087,6 +10181,8 @@ interface SignalSyncOpenNotification {
     scheduledAt: number;
     /** Position activation timestamp in milliseconds */
     pendingAt: number;
+    /** Optional human-readable description of signal reason */
+    note?: string;
     /** Unix timestamp in milliseconds when the notification was created */
     createdAt: number;
 }
@@ -10149,6 +10245,8 @@ interface SignalSyncCloseNotification {
     pendingAt: number;
     /** Why the signal was closed (take_profit | stop_loss | time_expired | closed) */
     closeReason: string;
+    /** Optional human-readable description of signal reason */
+    note?: string;
     /** Unix timestamp in milliseconds when the notification was created */
     createdAt: number;
 }
@@ -10253,6 +10351,8 @@ interface SignalScheduledNotification {
     scheduledAt: number;
     /** Current market price when signal was scheduled */
     currentPrice: number;
+    /** Optional human-readable description of signal reason */
+    note?: string;
     /** Unix timestamp in milliseconds when the tick result was created (from candle timestamp in backtest or execution context when in live) */
     createdAt: number;
 }
@@ -10305,6 +10405,8 @@ interface SignalCancelledNotification {
     scheduledAt: number;
     /** Pending timestamp in milliseconds (when position became pending/active at priceOpen) */
     pendingAt: number;
+    /** Optional human-readable description of signal reason */
+    note?: string;
     /** Unix timestamp in milliseconds when the tick result was created (from candle timestamp in backtest or execution context when in live) */
     createdAt: number;
 }
@@ -10397,6 +10499,8 @@ interface CancelScheduledCommitNotification {
     pnlCost: number;
     /** Total invested capital in USD */
     pnlEntries: number;
+    /** Optional human-readable description of signal reason */
+    note?: string;
     /** Unix timestamp in milliseconds when the notification was created */
     createdAt: number;
 }
@@ -10441,6 +10545,8 @@ interface ClosePendingCommitNotification {
     pnlCost: number;
     /** Total invested capital in USD */
     pnlEntries: number;
+    /** Optional human-readable description of signal reason */
+    note?: string;
     /** Unix timestamp in milliseconds when the notification was created */
     createdAt: number;
 }
@@ -11138,6 +11244,8 @@ interface StrategyEvent {
     pnl?: IStrategyPnL;
     /** Cost of this entry in USD (average-buy action only) */
     cost?: number;
+    /** Optional note from commit payload */
+    note?: string;
 }
 /**
  * Statistical data calculated from strategy events.
@@ -14071,6 +14179,36 @@ declare class BacktestUtils {
         exchangeName: ExchangeName;
         frameName: FrameName;
     }) => Promise<number>;
+    /**
+     * Returns the peak-to-trough PnL percentage distance between the position's highest profit and deepest drawdown.
+     *
+     * Computed as: max(0, peakPnlPercentage - fallPnlPercentage).
+     * Returns null if no pending signal exists.
+     *
+     * @param symbol - Trading pair symbol
+     * @param context - Execution context with strategyName, exchangeName, and frameName
+     * @returns peak-to-trough PnL percentage distance (≥ 0) or null if no active position
+     */
+    getMaxDrawdownDistancePnlPercentage: (symbol: string, context: {
+        strategyName: StrategyName;
+        exchangeName: ExchangeName;
+        frameName: FrameName;
+    }) => Promise<number>;
+    /**
+     * Returns the peak-to-trough PnL cost distance between the position's highest profit and deepest drawdown.
+     *
+     * Computed as: max(0, peakPnlCost - fallPnlCost).
+     * Returns null if no pending signal exists.
+     *
+     * @param symbol - Trading pair symbol
+     * @param context - Execution context with strategyName, exchangeName, and frameName
+     * @returns peak-to-trough PnL cost distance (≥ 0) or null if no active position
+     */
+    getMaxDrawdownDistancePnlCost: (symbol: string, context: {
+        strategyName: StrategyName;
+        exchangeName: ExchangeName;
+        frameName: FrameName;
+    }) => Promise<number>;
     /**
      * Checks whether the current price falls within the tolerance zone of any existing DCA entry level.
      * Use this to prevent duplicate DCA entries at the same price area.
@@ -14146,7 +14284,7 @@ declare class BacktestUtils {
      * @param symbol - Trading pair symbol
      * @param strategyName - Strategy name
      * @param context - Execution context with exchangeName and frameName
-     * @param cancelId - Optional cancellation ID for tracking user-initiated cancellations
+     * @param payload - Optional commit payload with id and note
      * @returns Promise that resolves when scheduled signal is cancelled
      *
      * @example
@@ -14156,14 +14294,14 @@ declare class BacktestUtils {
      *   exchangeName: "binance",
      *   frameName: "frame1",
      *   strategyName: "my-strategy"
-     * }, "manual-cancel-001");
+     * }, { id: "manual-cancel-001" });
      * ```
      */
     commitCancelScheduled: (symbol: string, context: {
         strategyName: StrategyName;
         exchangeName: ExchangeName;
         frameName: FrameName;
-    }, cancelId?: string) => Promise<void>;
+    }, payload?: Partial<CommitPayload>) => Promise<void>;
     /**
      * Closes the pending signal without stopping the strategy.
      *
@@ -14173,7 +14311,7 @@ declare class BacktestUtils {
      *
      * @param symbol - Trading pair symbol
      * @param context - Execution context with strategyName, exchangeName, and frameName
-     * @param closeId - Optional close ID for user-initiated closes
+     * @param payload - Optional commit payload with id and note
      * @returns Promise that resolves when pending signal is closed
      *
      * @example
@@ -14183,14 +14321,14 @@ declare class BacktestUtils {
      *   exchangeName: "binance",
      *   strategyName: "my-strategy",
      *   frameName: "1m"
-     * }, "manual-close-001");
+     * }, { id: "manual-close-001" });
      * ```
      */
     commitClosePending: (symbol: string, context: {
         strategyName: StrategyName;
         exchangeName: ExchangeName;
         frameName: FrameName;
-    }, closeId?: string) => Promise<void>;
+    }, payload?: Partial<CommitPayload>) => Promise<void>;
     /**
      * Executes partial close at profit level (moving toward TP).
      *
@@ -14495,7 +14633,7 @@ declare class BacktestUtils {
      *
      * @param symbol - Trading pair symbol
      * @param context - Execution context with strategyName, exchangeName, and frameName
-     * @param activateId - Optional activation ID for tracking user-initiated activations
+     * @param payload - Optional commit payload with id and note
      * @returns Promise that resolves when activation flag is set
      *
      * @example
@@ -14505,14 +14643,14 @@ declare class BacktestUtils {
      *   strategyName: "my-strategy",
      *   exchangeName: "binance",
      *   frameName: "1h"
-     * }, "manual-activate-001");
+     * }, { id: "manual-activate-001" });
      * ```
      */
     commitActivateScheduled: (symbol: string, context: {
         strategyName: StrategyName;
         exchangeName: ExchangeName;
         frameName: FrameName;
-    }, activateId?: string) => Promise<void>;
+    }, payload?: Partial<CommitPayload>) => Promise<void>;
     /**
      * Adds a new DCA entry to the active pending signal.
      *
@@ -15485,6 +15623,34 @@ declare class LiveUtils {
         strategyName: StrategyName;
         exchangeName: ExchangeName;
     }) => Promise<number>;
+    /**
+     * Returns the peak-to-trough PnL percentage distance between the position's highest profit and deepest drawdown.
+     *
+     * Computed as: max(0, peakPnlPercentage - fallPnlPercentage).
+     * Returns null if no pending signal exists.
+     *
+     * @param symbol - Trading pair symbol
+     * @param context - Execution context with strategyName and exchangeName
+     * @returns peak-to-trough PnL percentage distance (≥ 0) or null if no active position
+     */
+    getMaxDrawdownDistancePnlPercentage: (symbol: string, context: {
+        strategyName: StrategyName;
+        exchangeName: ExchangeName;
+    }) => Promise<number>;
+    /**
+     * Returns the peak-to-trough PnL cost distance between the position's highest profit and deepest drawdown.
+     *
+     * Computed as: max(0, peakPnlCost - fallPnlCost).
+     * Returns null if no pending signal exists.
+     *
+     * @param symbol - Trading pair symbol
+     * @param context - Execution context with strategyName and exchangeName
+     * @returns peak-to-trough PnL cost distance (≥ 0) or null if no active position
+     */
+    getMaxDrawdownDistancePnlCost: (symbol: string, context: {
+        strategyName: StrategyName;
+        exchangeName: ExchangeName;
+    }) => Promise<number>;
     /**
      * Checks whether the current price falls within the tolerance zone of any existing DCA entry level.
      * Use this to prevent duplicate DCA entries at the same price area.
@@ -15552,7 +15718,7 @@ declare class LiveUtils {
      * @param symbol - Trading pair symbol
      * @param strategyName - Strategy name
      * @param context - Execution context with exchangeName and frameName
-     * @param cancelId - Optional cancellation ID for tracking user-initiated cancellations
+     * @param payload - Optional commit payload with id and note
      * @returns Promise that resolves when scheduled signal is cancelled
      *
      * @example
@@ -15562,13 +15728,13 @@ declare class LiveUtils {
      *   exchangeName: "binance",
      *   frameName: "",
      *   strategyName: "my-strategy"
-     * }, "manual-cancel-001");
+     * }, { id: "manual-cancel-001" });
      * ```
      */
     commitCancelScheduled: (symbol: string, context: {
         strategyName: StrategyName;
         exchangeName: ExchangeName;
-    }, cancelId?: string) => Promise<void>;
+    }, payload?: Partial<CommitPayload>) => Promise<void>;
     /**
      * Closes the pending signal without stopping the strategy.
      *
@@ -15578,7 +15744,7 @@ declare class LiveUtils {
      *
      * @param symbol - Trading pair symbol
      * @param context - Execution context with strategyName and exchangeName
-     * @param closeId - Optional close ID for user-initiated closes
+     * @param payload - Optional commit payload with id and note
      * @returns Promise that resolves when pending signal is closed
      *
      * @example
@@ -15587,13 +15753,13 @@ declare class LiveUtils {
      * await Live.commitClose("BTCUSDT", {
      *   exchangeName: "binance",
      *   strategyName: "my-strategy"
-     * }, "manual-close-001");
+     * }, { id: "manual-close-001" });
      * ```
      */
     commitClosePending: (symbol: string, context: {
         strategyName: StrategyName;
         exchangeName: ExchangeName;
-    }, closeId?: string) => Promise<void>;
+    }, payload?: Partial<CommitPayload>) => Promise<void>;
     /**
      * Executes partial close at profit level (moving toward TP).
      *
@@ -15883,7 +16049,7 @@ declare class LiveUtils {
      *
      * @param symbol - Trading pair symbol
      * @param context - Execution context with strategyName and exchangeName
-     * @param activateId - Optional activation ID for tracking user-initiated activations
+     * @param payload - Optional commit payload with id and note
      * @returns Promise that resolves when activation flag is set
      *
      * @example
@@ -15892,13 +16058,13 @@ declare class LiveUtils {
      * await Live.commitActivateScheduled("BTCUSDT", {
      *   strategyName: "my-strategy",
      *   exchangeName: "binance"
-     * }, "manual-activate-001");
+     * }, { id: "manual-activate-001" });
      * ```
      */
     commitActivateScheduled: (symbol: string, context: {
         strategyName: StrategyName;
         exchangeName: ExchangeName;
-    }, activateId?: string) => Promise<void>;
+    }, payload?: Partial<CommitPayload>) => Promise<void>;
     /**
      * Adds a new DCA entry to the active pending signal.
      *
@@ -18253,55 +18419,608 @@ declare class MaxDrawdownUtils {
 declare const MaxDrawdown: MaxDrawdownUtils;
 
 /**
- * Utility class containing predefined trading constants for take-profit and stop-loss levels.
+ * Utility class for real-time position reflection: PNL, peak profit, and drawdown queries.
  *
- * Based on Kelly Criterion with exponential risk decay.
- * Values represent percentage of distance traveled towards final TP/SL target.
+ * Provides unified access to strategyCoreService position state methods with logging
+ * and full validation (strategy, exchange, frame, risk, actions).
+ * Works for both live and backtest modes via the `backtest` parameter.
+ * Exported as singleton instance for convenient usage.
  *
- * Example: If final TP is at +10% profit:
- * - TP_LEVEL1 (30) triggers when price reaches 30% of distance = +3% profit
- * - TP_LEVEL2 (60) triggers when price reaches 60% of distance = +6% profit
- * - TP_LEVEL3 (90) triggers when price reaches 90% of distance = +9% profit
+ * @example
+ * ```typescript
+ * import { Reflect } from "backtest-kit";
+ *
+ * // Get current unrealized PNL percentage
+ * const pnl = await Reflect.getPositionPnlPercent(
+ *   "BTCUSDT",
+ *   45000,
+ *   { strategyName: "my-strategy", exchangeName: "binance", frameName: "frame1" }
+ * );
+ * console.log(`PNL: ${pnl}%`);
+ *
+ * // Get peak profit reached
+ * const peakPnl = await Reflect.getPositionHighestPnlPercentage(
+ *   "BTCUSDT",
+ *   { strategyName: "my-strategy", exchangeName: "binance", frameName: "frame1" }
+ * );
+ * console.log(`Peak PNL: ${peakPnl}%`);
+ * ```
  */
-declare class ConstantUtils {
+declare class ReflectUtils {
     /**
-     * Take Profit Level 1 (Kelly-optimized early partial).
-     * Triggers at 30% of distance to final TP target.
-     * Lock in profit early, let rest run.
+     * Returns the unrealized PNL percentage for the current pending signal at currentPrice.
+     *
+     * Accounts for partial closes, DCA entries, slippage and fees.
+     * Returns null if no pending signal exists.
+     *
+     * @param symbol - Trading pair symbol
+     * @param currentPrice - Current market price
+     * @param context - Execution context with strategyName, exchangeName and frameName
+     * @param backtest - True if backtest mode, false if live mode (default: false)
+     * @returns Promise resolving to PNL percentage or null
+     *
+     * @example
+     * ```typescript
+     * const pnl = await Reflect.getPositionPnlPercent(
+     *   "BTCUSDT",
+     *   45000,
+     *   { strategyName: "my-strategy", exchangeName: "binance", frameName: "frame1" }
+     * );
+     * console.log(`PNL: ${pnl}%`);
+     * ```
      */
-    readonly TP_LEVEL1 = 30;
+    getPositionPnlPercent: (symbol: string, currentPrice: number, context: {
+        strategyName: StrategyName;
+        exchangeName: ExchangeName;
+        frameName: FrameName;
+    }, backtest?: boolean) => Promise<number | null>;
     /**
-     * Take Profit Level 2 (Kelly-optimized mid partial).
-     * Triggers at 60% of distance to final TP target.
-     * Secure majority of position while trend continues.
+     * Returns the unrealized PNL in dollars for the current pending signal at currentPrice.
+     *
+     * Calculated as: pnlPercentage / 100 × totalInvestedCost.
+     * Accounts for partial closes, DCA entries, slippage and fees.
+     * Returns null if no pending signal exists.
+     *
+     * @param symbol - Trading pair symbol
+     * @param currentPrice - Current market price
+     * @param context - Execution context with strategyName, exchangeName and frameName
+     * @param backtest - True if backtest mode, false if live mode (default: false)
+     * @returns Promise resolving to PNL in dollars or null
+     *
+     * @example
+     * ```typescript
+     * const pnlCost = await Reflect.getPositionPnlCost(
+     *   "BTCUSDT",
+     *   45000,
+     *   { strategyName: "my-strategy", exchangeName: "binance", frameName: "frame1" }
+     * );
+     * console.log(`PNL: $${pnlCost}`);
+     * ```
      */
-    readonly TP_LEVEL2 = 60;
+    getPositionPnlCost: (symbol: string, currentPrice: number, context: {
+        strategyName: StrategyName;
+        exchangeName: ExchangeName;
+        frameName: FrameName;
+    }, backtest?: boolean) => Promise<number | null>;
     /**
-     * Take Profit Level 3 (Kelly-optimized final partial).
-     * Triggers at 90% of distance to final TP target.
-     * Near-complete exit, minimal exposure remains.
+     * Returns the best price reached in the profit direction during this position's life.
+     *
+     * Returns null if no pending signal exists.
+     *
+     * @param symbol - Trading pair symbol
+     * @param context - Execution context with strategyName, exchangeName and frameName
+     * @param backtest - True if backtest mode, false if live mode (default: false)
+     * @returns Promise resolving to price or null
+     *
+     * @example
+     * ```typescript
+     * const peakPrice = await Reflect.getPositionHighestProfitPrice(
+     *   "BTCUSDT",
+     *   { strategyName: "my-strategy", exchangeName: "binance", frameName: "frame1" }
+     * );
+     * console.log(`Peak price: ${peakPrice}`);
+     * ```
      */
-    readonly TP_LEVEL3 = 90;
+    getPositionHighestProfitPrice: (symbol: string, context: {
+        strategyName: StrategyName;
+        exchangeName: ExchangeName;
+        frameName: FrameName;
+    }, backtest?: boolean) => Promise<number | null>;
     /**
-     * Stop Loss Level 1 (Kelly-optimized early warning).
-     * Triggers at 40% of distance to final SL target.
-     * Reduce exposure when setup weakens.
+     * Returns the timestamp when the best profit price was recorded during this position's life.
+     *
+     * Returns null if no pending signal exists.
+     *
+     * @param symbol - Trading pair symbol
+     * @param context - Execution context with strategyName, exchangeName and frameName
+     * @param backtest - True if backtest mode, false if live mode (default: false)
+     * @returns Promise resolving to timestamp in milliseconds or null
+     *
+     * @example
+     * ```typescript
+     * const ts = await Reflect.getPositionHighestProfitTimestamp(
+     *   "BTCUSDT",
+     *   { strategyName: "my-strategy", exchangeName: "binance", frameName: "frame1" }
+     * );
+     * console.log(`Peak at: ${new Date(ts).toISOString()}`);
+     * ```
      */
-    readonly SL_LEVEL1 = 40;
+    getPositionHighestProfitTimestamp: (symbol: string, context: {
+        strategyName: StrategyName;
+        exchangeName: ExchangeName;
+        frameName: FrameName;
+    }, backtest?: boolean) => Promise<number | null>;
     /**
-     * Stop Loss Level 2 (Kelly-optimized final exit).
-     * Triggers at 80% of distance to final SL target.
-     * Exit remaining position before catastrophic loss.
+     * Returns the PnL percentage at the moment the best profit price was recorded during this position's life.
+     *
+     * Returns null if no pending signal exists.
+     *
+     * @param symbol - Trading pair symbol
+     * @param context - Execution context with strategyName, exchangeName and frameName
+     * @param backtest - True if backtest mode, false if live mode (default: false)
+     * @returns Promise resolving to PnL percentage or null
+     *
+     * @example
+     * ```typescript
+     * const peakPnl = await Reflect.getPositionHighestPnlPercentage(
+     *   "BTCUSDT",
+     *   { strategyName: "my-strategy", exchangeName: "binance", frameName: "frame1" }
+     * );
+     * console.log(`Peak PNL: ${peakPnl}%`);
+     * ```
      */
-    readonly SL_LEVEL2 = 80;
-}
-/**
- * Global singleton instance of ConstantUtils.
- * Provides static-like access to predefined trading level constants.
- *
- * Kelly-optimized scaling strategy:
- * Profit side (pyramiding out):
- * - Close 33% at 30% progress (quick profit lock)
+    getPositionHighestPnlPercentage: (symbol: string, context: {
+        strategyName: StrategyName;
+        exchangeName: ExchangeName;
+        frameName: FrameName;
+    }, backtest?: boolean) => Promise<number | null>;
+    /**
+     * Returns the PnL cost (in quote currency) at the moment the best profit price was recorded during this position's life.
+     *
+     * Returns null if no pending signal exists.
+     *
+     * @param symbol - Trading pair symbol
+     * @param context - Execution context with strategyName, exchangeName and frameName
+     * @param backtest - True if backtest mode, false if live mode (default: false)
+     * @returns Promise resolving to PnL cost in quote currency or null
+     *
+     * @example
+     * ```typescript
+     * const peakCost = await Reflect.getPositionHighestPnlCost(
+     *   "BTCUSDT",
+     *   { strategyName: "my-strategy", exchangeName: "binance", frameName: "frame1" }
+     * );
+     * console.log(`Peak PNL: $${peakCost}`);
+     * ```
+     */
+    getPositionHighestPnlCost: (symbol: string, context: {
+        strategyName: StrategyName;
+        exchangeName: ExchangeName;
+        frameName: FrameName;
+    }, backtest?: boolean) => Promise<number | null>;
+    /**
+     * Returns whether breakeven was mathematically reachable at the highest profit price.
+     *
+     * Returns null if no pending signal exists.
+     *
+     * @param symbol - Trading pair symbol
+     * @param context - Execution context with strategyName, exchangeName and frameName
+     * @param backtest - True if backtest mode, false if live mode (default: false)
+     * @returns Promise resolving to true if breakeven was reachable at peak, false otherwise, or null
+     *
+     * @example
+     * ```typescript
+     * const wasReachable = await Reflect.getPositionHighestProfitBreakeven(
+     *   "BTCUSDT",
+     *   { strategyName: "my-strategy", exchangeName: "binance", frameName: "frame1" }
+     * );
+     * console.log(`Breakeven reachable at peak: ${wasReachable}`);
+     * ```
+     */
+    getPositionHighestProfitBreakeven: (symbol: string, context: {
+        strategyName: StrategyName;
+        exchangeName: ExchangeName;
+        frameName: FrameName;
+    }, backtest?: boolean) => Promise<boolean | null>;
+    /**
+     * Returns the number of minutes elapsed since the highest profit price was recorded.
+     *
+     * Returns null if no pending signal exists.
+     *
+     * @param symbol - Trading pair symbol
+     * @param context - Execution context with strategyName, exchangeName and frameName
+     * @param backtest - True if backtest mode, false if live mode (default: false)
+     * @returns Promise resolving to minutes since highest profit price was recorded, or null
+     *
+     * @example
+     * ```typescript
+     * const minutes = await Reflect.getPositionDrawdownMinutes(
+     *   "BTCUSDT",
+     *   { strategyName: "my-strategy", exchangeName: "binance", frameName: "frame1" }
+     * );
+     * console.log(`Pulling back from peak for ${minutes} minutes`);
+     * ```
+     */
+    getPositionDrawdownMinutes: (symbol: string, context: {
+        strategyName: StrategyName;
+        exchangeName: ExchangeName;
+        frameName: FrameName;
+    }, backtest?: boolean) => Promise<number | null>;
+    /**
+     * Returns the number of minutes elapsed since the highest profit price was recorded.
+     *
+     * Alias for getPositionDrawdownMinutes — measures how long the position has been
+     * pulling back from its peak profit level.
+     * Returns null if no pending signal exists.
+     *
+     * @param symbol - Trading pair symbol
+     * @param context - Execution context with strategyName, exchangeName and frameName
+     * @param backtest - True if backtest mode, false if live mode (default: false)
+     * @returns Promise resolving to minutes since last profit peak or null
+     *
+     * @example
+     * ```typescript
+     * const minutes = await Reflect.getPositionHighestProfitMinutes(
+     *   "BTCUSDT",
+     *   { strategyName: "my-strategy", exchangeName: "binance", frameName: "frame1" }
+     * );
+     * console.log(`Pulling back from peak for ${minutes} minutes`);
+     * ```
+     */
+    getPositionHighestProfitMinutes: (symbol: string, context: {
+        strategyName: StrategyName;
+        exchangeName: ExchangeName;
+        frameName: FrameName;
+    }, backtest?: boolean) => Promise<number | null>;
+    /**
+     * Returns the number of minutes elapsed since the worst loss price was recorded.
+     *
+     * Measures how long ago the deepest drawdown point occurred.
+     * Zero when called at the exact moment the trough was set.
+     * Returns null if no pending signal exists.
+     *
+     * @param symbol - Trading pair symbol
+     * @param context - Execution context with strategyName, exchangeName and frameName
+     * @param backtest - True if backtest mode, false if live mode (default: false)
+     * @returns Promise resolving to minutes since last drawdown trough or null
+     *
+     * @example
+     * ```typescript
+     * const minutes = await Reflect.getPositionMaxDrawdownMinutes(
+     *   "BTCUSDT",
+     *   { strategyName: "my-strategy", exchangeName: "binance", frameName: "frame1" }
+     * );
+     * console.log(`Drawdown trough was ${minutes} minutes ago`);
+     * ```
+     */
+    getPositionMaxDrawdownMinutes: (symbol: string, context: {
+        strategyName: StrategyName;
+        exchangeName: ExchangeName;
+        frameName: FrameName;
+    }, backtest?: boolean) => Promise<number | null>;
+    /**
+     * Returns the worst price reached in the loss direction during this position's life.
+     *
+     * Returns null if no pending signal exists.
+     *
+     * @param symbol - Trading pair symbol
+     * @param context - Execution context with strategyName, exchangeName and frameName
+     * @param backtest - True if backtest mode, false if live mode (default: false)
+     * @returns Promise resolving to price or null
+     *
+     * @example
+     * ```typescript
+     * const troughPrice = await Reflect.getPositionMaxDrawdownPrice(
+     *   "BTCUSDT",
+     *   { strategyName: "my-strategy", exchangeName: "binance", frameName: "frame1" }
+     * );
+     * console.log(`Worst price: ${troughPrice}`);
+     * ```
+     */
+    getPositionMaxDrawdownPrice: (symbol: string, context: {
+        strategyName: StrategyName;
+        exchangeName: ExchangeName;
+        frameName: FrameName;
+    }, backtest?: boolean) => Promise<number | null>;
+    /**
+     * Returns the timestamp when the worst loss price was recorded during this position's life.
+     *
+     * Returns null if no pending signal exists.
+     *
+     * @param symbol - Trading pair symbol
+     * @param context - Execution context with strategyName, exchangeName and frameName
+     * @param backtest - True if backtest mode, false if live mode (default: false)
+     * @returns Promise resolving to timestamp in milliseconds or null
+     *
+     * @example
+     * ```typescript
+     * const ts = await Reflect.getPositionMaxDrawdownTimestamp(
+     *   "BTCUSDT",
+     *   { strategyName: "my-strategy", exchangeName: "binance", frameName: "frame1" }
+     * );
+     * console.log(`Worst drawdown at: ${new Date(ts).toISOString()}`);
+     * ```
+     */
+    getPositionMaxDrawdownTimestamp: (symbol: string, context: {
+        strategyName: StrategyName;
+        exchangeName: ExchangeName;
+        frameName: FrameName;
+    }, backtest?: boolean) => Promise<number | null>;
+    /**
+     * Returns the PnL percentage at the moment the worst loss price was recorded during this position's life.
+     *
+     * Returns null if no pending signal exists.
+     *
+     * @param symbol - Trading pair symbol
+     * @param context - Execution context with strategyName, exchangeName and frameName
+     * @param backtest - True if backtest mode, false if live mode (default: false)
+     * @returns Promise resolving to PnL percentage or null
+     *
+     * @example
+     * ```typescript
+     * const worstPnl = await Reflect.getPositionMaxDrawdownPnlPercentage(
+     *   "BTCUSDT",
+     *   { strategyName: "my-strategy", exchangeName: "binance", frameName: "frame1" }
+     * );
+     * console.log(`Worst PNL: ${worstPnl}%`);
+     * ```
+     */
+    getPositionMaxDrawdownPnlPercentage: (symbol: string, context: {
+        strategyName: StrategyName;
+        exchangeName: ExchangeName;
+        frameName: FrameName;
+    }, backtest?: boolean) => Promise<number | null>;
+    /**
+     * Returns the PnL cost (in quote currency) at the moment the worst loss price was recorded during this position's life.
+     *
+     * Returns null if no pending signal exists.
+     *
+     * @param symbol - Trading pair symbol
+     * @param context - Execution context with strategyName, exchangeName and frameName
+     * @param backtest - True if backtest mode, false if live mode (default: false)
+     * @returns Promise resolving to PnL cost in quote currency or null
+     *
+     * @example
+     * ```typescript
+     * const worstCost = await Reflect.getPositionMaxDrawdownPnlCost(
+     *   "BTCUSDT",
+     *   { strategyName: "my-strategy", exchangeName: "binance", frameName: "frame1" }
+     * );
+     * console.log(`Worst PNL: $${worstCost}`);
+     * ```
+     */
+    getPositionMaxDrawdownPnlCost: (symbol: string, context: {
+        strategyName: StrategyName;
+        exchangeName: ExchangeName;
+        frameName: FrameName;
+    }, backtest?: boolean) => Promise<number | null>;
+    /**
+     * Returns the distance in PnL percentage between the current price and the highest profit peak.
+     *
+     * Result is ≥ 0. Returns null if no pending signal exists.
+     *
+     * @param symbol - Trading pair symbol
+     * @param context - Execution context with strategyName, exchangeName and frameName
+     * @param backtest - True if backtest mode, false if live mode (default: false)
+     * @returns Promise resolving to drawdown distance in PnL% (≥ 0) or null
+     *
+     * @example
+     * ```typescript
+     * const distance = await Reflect.getPositionHighestProfitDistancePnlPercentage(
+     *   "BTCUSDT",
+     *   { strategyName: "my-strategy", exchangeName: "binance", frameName: "frame1" }
+     * );
+     * console.log(`Dropped ${distance}% from peak`);
+     * ```
+     */
+    getPositionHighestProfitDistancePnlPercentage: (symbol: string, context: {
+        strategyName: StrategyName;
+        exchangeName: ExchangeName;
+        frameName: FrameName;
+    }, backtest?: boolean) => Promise<number | null>;
+    /**
+     * Returns the distance in PnL cost between the current price and the highest profit peak.
+     *
+     * Result is ≥ 0. Returns null if no pending signal exists.
+     *
+     * @param symbol - Trading pair symbol
+     * @param context - Execution context with strategyName, exchangeName and frameName
+     * @param backtest - True if backtest mode, false if live mode (default: false)
+     * @returns Promise resolving to drawdown distance in PnL cost (≥ 0) or null
+     *
+     * @example
+     * ```typescript
+     * const distance = await Reflect.getPositionHighestProfitDistancePnlCost(
+     *   "BTCUSDT",
+     *   { strategyName: "my-strategy", exchangeName: "binance", frameName: "frame1" }
+     * );
+     * console.log(`Dropped $${distance} from peak`);
+     * ```
+     */
+    getPositionHighestProfitDistancePnlCost: (symbol: string, context: {
+        strategyName: StrategyName;
+        exchangeName: ExchangeName;
+        frameName: FrameName;
+    }, backtest?: boolean) => Promise<number | null>;
+    /**
+     * Returns the distance in PnL percentage between the current price and the worst drawdown trough.
+     *
+     * Result is ≥ 0. Returns null if no pending signal exists.
+     *
+     * @param symbol - Trading pair symbol
+     * @param context - Execution context with strategyName, exchangeName and frameName
+     * @param backtest - True if backtest mode, false if live mode (default: false)
+     * @returns Promise resolving to recovery distance from worst drawdown trough in PnL% (≥ 0) or null
+     *
+     * @example
+     * ```typescript
+     * const distance = await Reflect.getPositionHighestMaxDrawdownPnlPercentage(
+     *   "BTCUSDT",
+     *   { strategyName: "my-strategy", exchangeName: "binance", frameName: "frame1" }
+     * );
+     * console.log(`${distance}% above worst trough`);
+     * ```
+     */
+    getPositionHighestMaxDrawdownPnlPercentage: (symbol: string, context: {
+        strategyName: StrategyName;
+        exchangeName: ExchangeName;
+        frameName: FrameName;
+    }, backtest?: boolean) => Promise<number | null>;
+    /**
+     * Returns the distance in PnL cost between the current price and the worst drawdown trough.
+     *
+     * Result is ≥ 0. Returns null if no pending signal exists.
+     *
+     * @param symbol - Trading pair symbol
+     * @param context - Execution context with strategyName, exchangeName and frameName
+     * @param backtest - True if backtest mode, false if live mode (default: false)
+     * @returns Promise resolving to recovery distance from worst drawdown trough in PnL cost (≥ 0) or null
+     *
+     * @example
+     * ```typescript
+     * const distance = await Reflect.getPositionHighestMaxDrawdownPnlCost(
+     *   "BTCUSDT",
+     *   { strategyName: "my-strategy", exchangeName: "binance", frameName: "frame1" }
+     * );
+     * console.log(`$${distance} above worst trough`);
+     * ```
+     */
+    getPositionHighestMaxDrawdownPnlCost: (symbol: string, context: {
+        strategyName: StrategyName;
+        exchangeName: ExchangeName;
+        frameName: FrameName;
+    }, backtest?: boolean) => Promise<number | null>;
+    /**
+     * Returns the peak-to-trough PnL percentage distance between the position's highest profit and deepest drawdown.
+     *
+     * Result is ≥ 0. Returns null if no pending signal exists.
+     *
+     * @param symbol - Trading pair symbol
+     * @param context - Execution context with strategyName, exchangeName and frameName
+     * @param backtest - True if backtest mode, false if live mode (default: false)
+     * @returns Promise resolving to peak-to-trough PnL percentage distance (≥ 0) or null
+     *
+     * @example
+     * ```typescript
+     * const distance = await Reflect.getMaxDrawdownDistancePnlPercentage(
+     *   "BTCUSDT",
+     *   { strategyName: "my-strategy", exchangeName: "binance", frameName: "frame1" }
+     * );
+     * console.log(`Peak-to-trough: ${distance}%`);
+     * ```
+     */
+    getMaxDrawdownDistancePnlPercentage: (symbol: string, context: {
+        strategyName: StrategyName;
+        exchangeName: ExchangeName;
+        frameName: FrameName;
+    }, backtest?: boolean) => Promise<number | null>;
+    /**
+     * Returns the peak-to-trough PnL cost distance between the position's highest profit and deepest drawdown.
+     *
+     * Result is ≥ 0. Returns null if no pending signal exists.
+     *
+     * @param symbol - Trading pair symbol
+     * @param context - Execution context with strategyName, exchangeName and frameName
+     * @param backtest - True if backtest mode, false if live mode (default: false)
+     * @returns Promise resolving to peak-to-trough PnL cost distance (≥ 0) or null
+     *
+     * @example
+     * ```typescript
+     * const distance = await Reflect.getMaxDrawdownDistancePnlCost(
+     *   "BTCUSDT",
+     *   { strategyName: "my-strategy", exchangeName: "binance", frameName: "frame1" }
+     * );
+     * console.log(`Peak-to-trough: $${distance}`);
+     * ```
+     */
+    getMaxDrawdownDistancePnlCost: (symbol: string, context: {
+        strategyName: StrategyName;
+        exchangeName: ExchangeName;
+        frameName: FrameName;
+    }, backtest?: boolean) => Promise<number | null>;
+}
+/**
+ * Singleton instance of ReflectUtils for convenient position state queries.
+ *
+ * @example
+ * ```typescript
+ * import { Reflect } from "backtest-kit";
+ *
+ * // Real-time PNL
+ * const pnl = await Reflect.getPositionPnlPercent(
+ *   "BTCUSDT",
+ *   45000,
+ *   { strategyName: "my-strategy", exchangeName: "binance", frameName: "frame1" }
+ * );
+ * console.log(`PNL: ${pnl}%`);
+ *
+ * // Peak profit
+ * const peakPnl = await Reflect.getPositionHighestPnlPercentage(
+ *   "BTCUSDT",
+ *   { strategyName: "my-strategy", exchangeName: "binance", frameName: "frame1" }
+ * );
+ * console.log(`Peak PNL: ${peakPnl}%`);
+ *
+ * // Drawdown from peak
+ * const drawdown = await Reflect.getPositionHighestProfitDistancePnlPercentage(
+ *   "BTCUSDT",
+ *   { strategyName: "my-strategy", exchangeName: "binance", frameName: "frame1" }
+ * );
+ * console.log(`Dropped ${drawdown}% from peak`);
+ * ```
+ */
+declare const Reflect: ReflectUtils;
+
+/**
+ * Utility class containing predefined trading constants for take-profit and stop-loss levels.
+ *
+ * Based on Kelly Criterion with exponential risk decay.
+ * Values represent percentage of distance traveled towards final TP/SL target.
+ *
+ * Example: If final TP is at +10% profit:
+ * - TP_LEVEL1 (30) triggers when price reaches 30% of distance = +3% profit
+ * - TP_LEVEL2 (60) triggers when price reaches 60% of distance = +6% profit
+ * - TP_LEVEL3 (90) triggers when price reaches 90% of distance = +9% profit
+ */
+declare class ConstantUtils {
+    /**
+     * Take Profit Level 1 (Kelly-optimized early partial).
+     * Triggers at 30% of distance to final TP target.
+     * Lock in profit early, let rest run.
+     */
+    readonly TP_LEVEL1 = 30;
+    /**
+     * Take Profit Level 2 (Kelly-optimized mid partial).
+     * Triggers at 60% of distance to final TP target.
+     * Secure majority of position while trend continues.
+     */
+    readonly TP_LEVEL2 = 60;
+    /**
+     * Take Profit Level 3 (Kelly-optimized final partial).
+     * Triggers at 90% of distance to final TP target.
+     * Near-complete exit, minimal exposure remains.
+     */
+    readonly TP_LEVEL3 = 90;
+    /**
+     * Stop Loss Level 1 (Kelly-optimized early warning).
+     * Triggers at 40% of distance to final SL target.
+     * Reduce exposure when setup weakens.
+     */
+    readonly SL_LEVEL1 = 40;
+    /**
+     * Stop Loss Level 2 (Kelly-optimized final exit).
+     * Triggers at 80% of distance to final SL target.
+     * Exit remaining position before catastrophic loss.
+     */
+    readonly SL_LEVEL2 = 80;
+}
+/**
+ * Global singleton instance of ConstantUtils.
+ * Provides static-like access to predefined trading level constants.
+ *
+ * Kelly-optimized scaling strategy:
+ * Profit side (pyramiding out):
+ * - Close 33% at 30% progress (quick profit lock)
  * - Close 33% at 60% progress (secure gains)
  * - Close 34% at 90% progress (exit near target)
  *
@@ -20217,7 +20936,7 @@ declare const Exchange: ExchangeUtils;
  * Generic function type that accepts any arguments and returns any value.
  * Used as a constraint for cached functions.
  */
-type Function = (...args: any[]) => any;
+type Function$1 = (...args: any[]) => any;
 /**
  * Async function type for file-cached functions.
  * First argument is always `symbol: string`, followed by optional spread args.
@@ -20228,7 +20947,7 @@ type CacheFileFunction = (symbol: string, ...args: any[]) => Promise<any>;
  * For example, for a function type `(symbol: string, arg1: number, arg2: string) => Promise<void>`,
  * this type will infer the rest of the arguments as `[arg1: number, arg2: string]`.
  */
-type DropFirst<T extends (...args: any) => any> = T extends (first: any, ...rest: infer R) => any ? R : never;
+type DropFirst$1<T extends (...args: any) => any> = T extends (first: any, ...rest: infer R) => any ? R : never;
 /**
  * Extracts the `key` generator argument tuple from a `CacheFileFunction`.
  * The first two arguments are always `symbol: string` and `alignMs: number` (aligned timestamp),
@@ -20240,7 +20959,7 @@ type DropFirst<T extends (...args: any) => any> = T extends (first: any, ...rest
 type CacheFileKeyArgs<T extends CacheFileFunction> = [
     symbol: string,
     alignMs: number,
-    ...rest: DropFirst<T>
+    ...rest: DropFirst$1<T>
 ];
 /**
  * Utility class for function caching with timeframe-based invalidation.
@@ -20301,7 +21020,7 @@ declare class CacheUtils {
      * const result3 = cachedCalculate("BTCUSDT", 14); // Cached (same key, same interval)
      * ```
      */
-    fn: <T extends Function, K = symbol>(run: T, context: {
+    fn: <T extends Function$1, K = symbol>(run: T, context: {
         interval: CandleInterval;
         key?: (args: Parameters<T>) => K;
     }) => T & {
@@ -20371,13 +21090,19 @@ declare class CacheUtils {
      * Cache.dispose(calculateIndicator);
      * ```
      */
-    dispose: <T extends Function>(run: T) => void;
+    dispose: <T extends Function$1>(run: T) => void;
     /**
      * Clears all memoized CacheFnInstance and CacheFileInstance objects.
      * Call this when process.cwd() changes between strategy iterations
      * so new instances are created with the updated base path.
      */
     clear: () => void;
+    /**
+     * Resets the CacheFileInstance index counter to zero.
+     * This is useful when process.cwd() changes between strategy iterations to ensure
+     * that new CacheFileInstance objects start with index 0 and do not collide with old instances.
+     */
+    resetCounter: () => void;
 }
 /**
  * Singleton instance of CacheUtils for convenient function caching.
@@ -20396,15 +21121,34 @@ declare class CacheUtils {
 declare const Cache: CacheUtils;
 
 /**
- * User-implemented function fired once per interval boundary.
- * Receives `when` from the caller (sourced from execution context).
+ * Generic function type that accepts any arguments and returns any value.
+ * Used as a constraint for interval functions.
+ */
+type Function = (...args: any[]) => any;
+/**
+ * Async function type for file-interval functions.
+ * First argument is always `symbol: string`, followed by optional spread args.
  */
-type TIntervalFn<T extends object = object> = (symbol: string, when: Date) => Promise<T | null>;
+type IntervalFileFunction = (symbol: string, ...args: any[]) => Promise<any>;
 /**
- * Wrapped function returned by `Interval.fn` and `Interval.file`.
- * `when` is resolved internally from the execution context — callers pass only `symbol`.
+ * Utility type to drop the first argument from a function type.
+ * For example, for `(symbol: string, arg1: number, arg2: string) => Promise<void>`,
+ * this will infer `[arg1: number, arg2: string]`.
  */
-type TIntervalWrappedFn<T extends object = object> = (symbol: string) => Promise<T | null>;
+type DropFirst<T extends (...args: any) => any> = T extends (first: any, ...rest: infer R) => any ? R : never;
+/**
+ * Extracts the `key` generator argument tuple from an `IntervalFileFunction`.
+ * The first two arguments are always `symbol: string` and `alignMs: number` (aligned timestamp),
+ * followed by the rest of the original function's arguments.
+ *
+ * For example, for `(symbol: string, arg1: number) => Promise<void>`,
+ * this will produce `[symbol: string, alignMs: number, arg1: number]`.
+ */
+type IntervalFileKeyArgs<T extends IntervalFileFunction> = [
+    symbol: string,
+    alignMs: number,
+    ...rest: DropFirst<T>
+];
 /**
  * Utility class for wrapping signal functions with once-per-interval firing.
  * Provides two modes: in-memory (`fn`) and persistent file-based (`file`).
@@ -20441,20 +21185,31 @@ declare class IntervalUtils {
      *
      * @param run - Signal function to wrap
      * @param context.interval - Candle interval that controls the firing boundary
-     * @returns Wrapped function with the same signature as `TIntervalFn<T>`, plus a `clear()` method
+     * @param context.key - Optional key generator for argument-based state separation
+     * @returns Wrapped function with the same signature as `F`, plus a `clear()` method
      *
      * @example
      * ```typescript
+     * // Without extra args
      * const fireOnce = Interval.fn(mySignalFn, { interval: "15m" });
-     *
      * await fireOnce("BTCUSDT"); // → T or null  (fn called)
      * await fireOnce("BTCUSDT"); // → null       (same interval, skipped)
+     *
+     * // With extra args and key
+     * const fireOnce = Interval.fn(mySignalFn, {
+     *   interval: "15m",
+     *   key: ([symbol, period]) => `${symbol}_${period}`,
+     * });
+     * await fireOnce("BTCUSDT", 14); // → T or null
+     * await fireOnce("BTCUSDT", 28); // → T or null (separate state)
      * ```
      */
-    fn: <T extends object>(run: TIntervalFn<T>, context: {
+    fn: <F extends Function>(run: F, context: {
         interval: CandleInterval;
-    }) => TIntervalWrappedFn<T> & {
+        key?: (args: Parameters<F>) => string;
+    }) => F & {
         clear(): void;
+        gc(): number | undefined;
     };
     /**
      * Wrap an async signal function with persistent file-based once-per-interval firing.
@@ -20466,24 +21221,30 @@ declare class IntervalUtils {
      * The `run` function reference is used as the memoization key for the underlying
      * `IntervalFileInstance`, so each unique function reference gets its own isolated instance.
      *
-     * @template T - Async function type to wrap
+     * @template F - Concrete async function type
      * @param run - Async signal function to wrap with persistent once-per-interval firing
      * @param context.interval - Candle interval that controls the firing boundary
      * @param context.name - Human-readable bucket name; becomes the directory prefix
-     * @returns Wrapped function with the same signature as `T`, plus an async `clear()` method
-     *   that deletes persisted records from disk and disposes the memoized instance
+     * @param context.key - Optional entity key generator. Receives `[symbol, alignMs, ...rest]`.
+     *                      Default: `([symbol, alignMs]) => \`${symbol}_${alignMs}\``
+     * @returns Wrapped function with the same signature as `F`, plus an async `clear()` method
      *
      * @example
      * ```typescript
-     * const fetchSignal = async (symbol: string, when: Date) => { ... };
-     * const fireOnce = Interval.file(fetchSignal, { interval: "1h", name: "fetchSignal" });
-     * await fireOnce.clear(); // delete disk records so the function fires again next call
+     * const fetchSignal = async (symbol: string, period: number) => { ... };
+     * const fireOnce = Interval.file(fetchSignal, {
+     *   interval: "1h",
+     *   name: "fetchSignal",
+     *   key: ([symbol, alignMs, period]) => `${symbol}_${alignMs}_${period}`,
+     * });
+     * await fireOnce("BTCUSDT", 14);
      * ```
      */
-    file: <T extends object>(run: TIntervalFn<T>, context: {
+    file: <F extends IntervalFileFunction>(run: F, context: {
         interval: CandleInterval;
         name: string;
-    }) => TIntervalWrappedFn<T> & {
+        key?: (args: IntervalFileKeyArgs<F>) => string;
+    }) => F & {
         clear(): Promise<void>;
     };
     /**
@@ -20501,14 +21262,19 @@ declare class IntervalUtils {
      * Interval.dispose(mySignalFn);
      * ```
      */
-    dispose: (run: TIntervalFn<object>) => void;
+    dispose: (run: Function) => void;
     /**
-     * Clears all memoized `IntervalFnInstance` and `IntervalFileInstance` objects and
-     * resets the `IntervalFileInstance` index counter.
+     * Clears all memoized `IntervalFnInstance` and `IntervalFileInstance` objects.
      * Call this when `process.cwd()` changes between strategy iterations
      * so new instances are created with the updated base path.
      */
     clear: () => void;
+    /**
+     * Resets the IntervalFileInstance index counter to zero.
+     * This is useful when process.cwd() changes between strategy iterations to ensure
+     * that new IntervalFileInstance objects start with index 0 and do not collide with old instances.
+     */
+    resetCounter: () => void;
 }
 /**
  * Singleton instance of `IntervalUtils` for convenient once-per-interval signal firing.
@@ -20961,12 +21727,13 @@ declare class StrategyMarkdownService {
      * @param context - Strategy context with strategyName, exchangeName, frameName
      * @param timestamp - Timestamp from StrategyCommitContract (execution context time)
      * @param cancelId - Optional identifier for the cancellation reason
+     * @param note - Optional note from commit payload
      */
     cancelScheduled: (symbol: string, isBacktest: boolean, context: {
         strategyName: StrategyName;
         exchangeName: ExchangeName;
         frameName: FrameName;
-    }, timestamp: number, signalId: string, pnl: IStrategyPnL, cancelId?: string) => Promise<void>;
+    }, timestamp: number, signalId: string, pnl: IStrategyPnL, cancelId?: string, note?: string) => Promise<void>;
     /**
      * Records a close-pending event when a pending signal is closed.
      *
@@ -20975,12 +21742,13 @@ declare class StrategyMarkdownService {
      * @param context - Strategy context with strategyName, exchangeName, frameName
      * @param timestamp - Timestamp from StrategyCommitContract (execution context time)
      * @param closeId - Optional identifier for the close reason
+     * @param note - Optional note from commit payload
      */
     closePending: (symbol: string, isBacktest: boolean, context: {
         strategyName: StrategyName;
         exchangeName: ExchangeName;
         frameName: FrameName;
-    }, timestamp: number, signalId: string, pnl: IStrategyPnL, closeId?: string) => Promise<void>;
+    }, timestamp: number, signalId: string, pnl: IStrategyPnL, closeId?: string, note?: string) => Promise<void>;
     /**
      * Records a partial-profit event when a portion of the position is closed at profit.
      *
@@ -21112,12 +21880,13 @@ declare class StrategyMarkdownService {
      * @param scheduledAt - Signal creation timestamp in milliseconds
      * @param pendingAt - Pending timestamp in milliseconds
      * @param activateId - Optional identifier for the activation reason
+     * @param note - Optional note from commit payload
      */
     activateScheduled: (symbol: string, currentPrice: number, isBacktest: boolean, context: {
         strategyName: StrategyName;
         exchangeName: ExchangeName;
         frameName: FrameName;
-    }, timestamp: number, signalId: string, pnl: IStrategyPnL, totalPartials: number, position: "long" | "short", priceOpen: number, priceTakeProfit: number, priceStopLoss: number, originalPriceTakeProfit: number, originalPriceStopLoss: number, scheduledAt: number, pendingAt: number, totalEntries: number, originalPriceOpen: number, activateId?: string) => Promise<void>;
+    }, timestamp: number, signalId: string, pnl: IStrategyPnL, totalPartials: number, position: "long" | "short", priceOpen: number, priceTakeProfit: number, priceStopLoss: number, originalPriceTakeProfit: number, originalPriceStopLoss: number, scheduledAt: number, pendingAt: number, totalEntries: number, originalPriceOpen: number, activateId?: string, note?: string) => Promise<void>;
     /**
      * Records an average-buy (DCA) event when a new averaging entry is added to an open position.
      *
@@ -25357,6 +26126,40 @@ declare class StrategyConnectionService implements TStrategy$1 {
         exchangeName: ExchangeName;
         frameName: FrameName;
     }) => Promise<number | null>;
+    /**
+     * Returns the peak-to-trough PnL percentage distance between the position's highest profit and deepest drawdown.
+     *
+     * Resolves current price via priceMetaService and delegates to
+     * ClientStrategy.getMaxDrawdownDistancePnlPercentage().
+     * Returns null if no pending signal exists.
+     *
+     * @param backtest - Whether running in backtest mode
+     * @param symbol - Trading pair symbol
+     * @param context - Execution context with strategyName, exchangeName, frameName
+     * @returns Promise resolving to peak-to-trough PnL percentage distance (≥ 0) or null
+     */
+    getMaxDrawdownDistancePnlPercentage: (backtest: boolean, symbol: string, context: {
+        strategyName: StrategyName;
+        exchangeName: ExchangeName;
+        frameName: FrameName;
+    }) => Promise<number | null>;
+    /**
+     * Returns the peak-to-trough PnL cost distance between the position's highest profit and deepest drawdown.
+     *
+     * Resolves current price via priceMetaService and delegates to
+     * ClientStrategy.getMaxDrawdownDistancePnlCost().
+     * Returns null if no pending signal exists.
+     *
+     * @param backtest - Whether running in backtest mode
+     * @param symbol - Trading pair symbol
+     * @param context - Execution context with strategyName, exchangeName, frameName
+     * @returns Promise resolving to peak-to-trough PnL cost distance (≥ 0) or null
+     */
+    getMaxDrawdownDistancePnlCost: (backtest: boolean, symbol: string, context: {
+        strategyName: StrategyName;
+        exchangeName: ExchangeName;
+        frameName: FrameName;
+    }) => Promise<number | null>;
     /**
      * Disposes the ClientStrategy instance for the given context.
      *
@@ -25398,14 +26201,14 @@ declare class StrategyConnectionService implements TStrategy$1 {
      * @param backtest - Whether running in backtest mode
      * @param symbol - Trading pair symbol
      * @param ctx - Context with strategyName, exchangeName, frameName
-     * @param cancelId - Optional cancellation ID for user-initiated cancellations
+     * @param payload - Optional commit payload with id and note
      * @returns Promise that resolves when scheduled signal is cancelled
      */
     cancelScheduled: (backtest: boolean, symbol: string, context: {
         strategyName: StrategyName;
         exchangeName: ExchangeName;
         frameName: FrameName;
-    }, cancelId?: string) => Promise<void>;
+    }, payload?: Partial<CommitPayload>) => Promise<void>;
     /**
      * Closes the pending signal without stopping the strategy.
      *
@@ -25419,14 +26222,14 @@ declare class StrategyConnectionService implements TStrategy$1 {
      * @param backtest - Whether running in backtest mode
      * @param symbol - Trading pair symbol
      * @param context - Context with strategyName, exchangeName, frameName
-     * @param closeId - Optional close ID for user-initiated closes
+     * @param payload - Optional commit payload with id and note
      * @returns Promise that resolves when pending signal is closed
      */
     closePending: (backtest: boolean, symbol: string, context: {
         strategyName: StrategyName;
         exchangeName: ExchangeName;
         frameName: FrameName;
-    }, closeId?: string) => Promise<void>;
+    }, payload?: Partial<CommitPayload>) => Promise<void>;
     /**
      * Checks whether `partialProfit` would succeed without executing it.
      * Delegates to `ClientStrategy.validatePartialProfit()` — no throws, pure boolean result.
@@ -25678,7 +26481,7 @@ declare class StrategyConnectionService implements TStrategy$1 {
      * @param backtest - Whether running in backtest mode
      * @param symbol - Trading pair symbol
      * @param context - Execution context with strategyName, exchangeName, frameName
-     * @param activateId - Optional identifier for the activation reason
+     * @param payload - Optional commit payload with id and note
      * @returns Promise that resolves when activation flag is set
      *
      * @example
@@ -25688,7 +26491,7 @@ declare class StrategyConnectionService implements TStrategy$1 {
      *   false,
      *   "BTCUSDT",
      *   { strategyName: "my-strategy", exchangeName: "binance", frameName: "" },
-     *   "manual-activation"
+     *   { id: "manual-activation" }
      * );
      * ```
      */
@@ -25696,7 +26499,7 @@ declare class StrategyConnectionService implements TStrategy$1 {
         strategyName: StrategyName;
         exchangeName: ExchangeName;
         frameName: FrameName;
-    }, activateId?: string) => Promise<void>;
+    }, payload?: Partial<CommitPayload>) => Promise<void>;
     /**
      * Checks whether `averageBuy` would succeed without executing it.
      * Delegates to `ClientStrategy.validateAverageBuy()` — no throws, pure boolean result.
@@ -26938,14 +27741,14 @@ declare class StrategyCoreService implements TStrategy {
      * @param backtest - Whether running in backtest mode
      * @param symbol - Trading pair symbol
      * @param ctx - Context with strategyName, exchangeName, frameName
-     * @param cancelId - Optional cancellation ID for user-initiated cancellations
+     * @param payload - Optional commit payload with id and note
      * @returns Promise that resolves when scheduled signal is cancelled
      */
     cancelScheduled: (backtest: boolean, symbol: string, context: {
         strategyName: StrategyName;
         exchangeName: ExchangeName;
         frameName: FrameName;
-    }, cancelId?: string) => Promise<void>;
+    }, payload?: Partial<CommitPayload>) => Promise<void>;
     /**
      * Closes the pending signal without stopping the strategy.
      *
@@ -26960,14 +27763,14 @@ declare class StrategyCoreService implements TStrategy {
      * @param backtest - Whether running in backtest mode
      * @param symbol - Trading pair symbol
      * @param context - Context with strategyName, exchangeName, frameName
-     * @param closeId - Optional close ID for user-initiated closes
+     * @param payload - Optional commit payload with id and note
      * @returns Promise that resolves when pending signal is closed
      */
     closePending: (backtest: boolean, symbol: string, context: {
         strategyName: StrategyName;
         exchangeName: ExchangeName;
         frameName: FrameName;
-    }, closeId?: string) => Promise<void>;
+    }, payload?: Partial<CommitPayload>) => Promise<void>;
     /**
      * Disposes the ClientStrategy instance for the given context.
      *
@@ -27243,7 +28046,7 @@ declare class StrategyCoreService implements TStrategy {
      * @param backtest - Whether running in backtest mode
      * @param symbol - Trading pair symbol
      * @param context - Execution context with strategyName, exchangeName, frameName
-     * @param activateId - Optional identifier for the activation reason
+     * @param payload - Optional commit payload with id and note
      * @returns Promise that resolves when activation flag is set
      *
      * @example
@@ -27253,7 +28056,7 @@ declare class StrategyCoreService implements TStrategy {
      *   false,
      *   "BTCUSDT",
      *   { strategyName: "my-strategy", exchangeName: "binance", frameName: "" },
-     *   "manual-activation"
+     *   { id: "manual-activation" }
      * );
      * ```
      */
@@ -27261,7 +28064,7 @@ declare class StrategyCoreService implements TStrategy {
         strategyName: StrategyName;
         exchangeName: ExchangeName;
         frameName: FrameName;
-    }, activateId?: string) => Promise<void>;
+    }, payload?: Partial<CommitPayload>) => Promise<void>;
     /**
      * Checks whether `averageBuy` would succeed without executing it.
      * Validates context, then delegates to StrategyConnectionService.validateAverageBuy().
@@ -27592,6 +28395,38 @@ declare class StrategyCoreService implements TStrategy {
         exchangeName: ExchangeName;
         frameName: FrameName;
     }) => Promise<number | null>;
+    /**
+     * Returns the peak-to-trough PnL percentage distance between the position's highest profit and deepest drawdown.
+     *
+     * Delegates to StrategyConnectionService.getMaxDrawdownDistancePnlPercentage().
+     * Returns null if no pending signal exists.
+     *
+     * @param backtest - Whether running in backtest mode
+     * @param symbol - Trading pair symbol
+     * @param context - Execution context with strategyName, exchangeName, frameName
+     * @returns Promise resolving to peak-to-trough PnL percentage distance (≥ 0) or null
+     */
+    getMaxDrawdownDistancePnlPercentage: (backtest: boolean, symbol: string, context: {
+        strategyName: StrategyName;
+        exchangeName: ExchangeName;
+        frameName: FrameName;
+    }) => Promise<number | null>;
+    /**
+     * Returns the peak-to-trough PnL cost distance between the position's highest profit and deepest drawdown.
+     *
+     * Delegates to StrategyConnectionService.getMaxDrawdownDistancePnlCost().
+     * Returns null if no pending signal exists.
+     *
+     * @param backtest - Whether running in backtest mode
+     * @param symbol - Trading pair symbol
+     * @param context - Execution context with strategyName, exchangeName, frameName
+     * @returns Promise resolving to peak-to-trough PnL cost distance (≥ 0) or null
+     */
+    getMaxDrawdownDistancePnlCost: (backtest: boolean, symbol: string, context: {
+        strategyName: StrategyName;
+        exchangeName: ExchangeName;
+        frameName: FrameName;
+    }) => Promise<number | null>;
 }
 
 /**
@@ -29987,7 +30822,7 @@ declare class StrategyReportService {
         strategyName: StrategyName;
         exchangeName: ExchangeName;
         frameName: FrameName;
-    }, timestamp: number, signalId: string, pnl: IStrategyPnL, totalPartials: number, cancelId?: string) => Promise<void>;
+    }, timestamp: number, signalId: string, pnl: IStrategyPnL, totalPartials: number, cancelId?: string, note?: string) => Promise<void>;
     /**
      * Logs a close-pending event when a pending signal is closed.
      */
@@ -29995,7 +30830,7 @@ declare class StrategyReportService {
         strategyName: StrategyName;
         exchangeName: ExchangeName;
         frameName: FrameName;
-    }, timestamp: number, signalId: string, pnl: IStrategyPnL, totalPartials: number, closeId?: string) => Promise<void>;
+    }, timestamp: number, signalId: string, pnl: IStrategyPnL, totalPartials: number, closeId?: string, note?: string) => Promise<void>;
     /**
      * Logs a partial-profit event when a portion of the position is closed at profit.
      */
@@ -30043,7 +30878,7 @@ declare class StrategyReportService {
         strategyName: StrategyName;
         exchangeName: ExchangeName;
         frameName: FrameName;
-    }, timestamp: number, signalId: string, pnl: IStrategyPnL, totalPartials: number, position: "long" | "short", priceOpen: number, priceTakeProfit: number, priceStopLoss: number, originalPriceTakeProfit: number, originalPriceStopLoss: number, scheduledAt: number, pendingAt: number, totalEntries: number, originalPriceOpen: number, activateId?: string) => Promise<void>;
+    }, timestamp: number, signalId: string, pnl: IStrategyPnL, totalPartials: number, position: "long" | "short", priceOpen: number, priceTakeProfit: number, priceStopLoss: number, originalPriceTakeProfit: number, originalPriceStopLoss: number, scheduledAt: number, pendingAt: number, totalEntries: number, originalPriceOpen: number, activateId?: string, note?: string) => Promise<void>;
     /**
      * Logs an average-buy (DCA) event when a new averaging entry is added to an open position.
      */
@@ -30443,4 +31278,4 @@ declare const getTotalClosed: (signal: Signal) => {
     remainingCostBasis: number;
 };
 
-export { ActionBase, type ActivateScheduledCommit, type ActivateScheduledCommitNotification, type ActivePingContract, type AverageBuyCommit, type AverageBuyCommitNotification, Backtest, type BacktestStatisticsModel, Breakeven, type BreakevenAvailableNotification, type BreakevenCommit, type BreakevenCommitNotification, type BreakevenContract, type BreakevenData, type BreakevenEvent, type BreakevenStatisticsModel, Broker, type BrokerAverageBuyPayload, BrokerBase, type BrokerBreakevenPayload, type BrokerPartialLossPayload, type BrokerPartialProfitPayload, type BrokerSignalClosePayload, type BrokerSignalOpenPayload, type BrokerTrailingStopPayload, type BrokerTrailingTakePayload, Cache, type CancelScheduledCommit, type CancelScheduledCommitNotification, type CandleData, type CandleInterval, type ClosePendingCommit, type ClosePendingCommitNotification, type ColumnConfig, type ColumnModel, Constant, type CriticalErrorNotification, type DoneContract, Dump, type EntityId, Exchange, ExecutionContextService, type FrameInterval, type GlobalConfig, Heat, type HeatmapStatisticsModel, HighestProfit, type HighestProfitContract, type HighestProfitEvent, type HighestProfitStatisticsModel, type IActionSchema, type IActivateScheduledCommitRow, type IAggregatedTradeData, type IBidData, type IBreakevenCommitRow, type IBroker, type ICandleData, type ICommitRow, type IDumpContext, type IDumpInstance, type IExchangeSchema, type IFrameSchema, type IHeatmapRow, type ILog, type ILogEntry, type ILogger, type IMarkdownDumpOptions, type IMemoryInstance, type INotificationUtils, type IOrderBookData, type IPartialLossCommitRow, type IPartialProfitCommitRow, type IPersistBase, type IPositionSizeATRParams, type IPositionSizeFixedPercentageParams, type IPositionSizeKellyParams, type IPublicAction, type IPublicCandleData, type IPublicSignalRow, type IReportDumpOptions, type IRiskActivePosition, type IRiskCheckArgs, type IRiskSchema, type IRiskSignalRow, type IRiskValidation, type IRiskValidationFn, type IRiskValidationPayload, type IScheduledSignalCancelRow, type IScheduledSignalRow, type ISignalDto, type ISignalIntervalDto, type ISignalRow, type ISizingCalculateParams, type ISizingCalculateParamsATR, type ISizingCalculateParamsFixedPercentage, type ISizingCalculateParamsKelly, type ISizingParams, type ISizingParamsATR, type ISizingParamsFixedPercentage, type ISizingParamsKelly, type ISizingSchema, type ISizingSchemaATR, type ISizingSchemaFixedPercentage, type ISizingSchemaKelly, type IStorageSignalRow, type IStorageUtils, type IStrategyPnL, type IStrategyResult, type IStrategySchema, type IStrategyTickResult, type IStrategyTickResultActive, type IStrategyTickResultCancelled, type IStrategyTickResultClosed, type IStrategyTickResultIdle, type IStrategyTickResultOpened, type IStrategyTickResultScheduled, type IStrategyTickResultWaiting, type ITrailingStopCommitRow, type ITrailingTakeCommitRow, type IWalkerResults, type IWalkerSchema, type IWalkerStrategyResult, type InfoErrorNotification, Interval, type IntervalData, Live, type LiveStatisticsModel, Log, type LogData, Markdown, MarkdownFileBase, MarkdownFolderBase, type MarkdownName, MarkdownWriter, MaxDrawdown, type MaxDrawdownContract, type MaxDrawdownEvent, type MaxDrawdownStatisticsModel, type MeasureData, Memory, type MemoryData, type MessageModel, type MessageRole, type MessageToolCall, MethodContextService, type MetricStats, Notification, NotificationBacktest, type NotificationData, NotificationLive, type NotificationModel, Partial$1 as Partial, type PartialData, type PartialEvent, type PartialLossAvailableNotification, type PartialLossCommit, type PartialLossCommitNotification, type PartialLossContract, type PartialProfitAvailableNotification, type PartialProfitCommit, type PartialProfitCommitNotification, type PartialProfitContract, type PartialStatisticsModel, Performance, type PerformanceContract, type PerformanceMetricType, type PerformanceStatisticsModel, PersistBase, PersistBreakevenAdapter, PersistCandleAdapter, PersistIntervalAdapter, PersistLogAdapter, PersistMeasureAdapter, PersistMemoryAdapter, PersistNotificationAdapter, PersistPartialAdapter, PersistRiskAdapter, PersistScheduleAdapter, PersistSignalAdapter, PersistStorageAdapter, Position, PositionSize, type ProgressBacktestContract, type ProgressWalkerContract, Report, ReportBase, type ReportName, ReportWriter, Risk, type RiskContract, type RiskData, type RiskEvent, type RiskRejectionNotification, type RiskStatisticsModel, Schedule, type ScheduleData, type SchedulePingContract, type ScheduleStatisticsModel, type ScheduledEvent, type SignalCancelledNotification, type SignalCloseContract, type SignalClosedNotification, type SignalData, type SignalInterval, type SignalOpenContract, type SignalOpenedNotification, type SignalScheduledNotification, type SignalSyncCloseNotification, type SignalSyncContract, type SignalSyncOpenNotification, Storage, StorageBacktest, type StorageData, StorageLive, Strategy, type StrategyActionType, type StrategyCancelReason, type StrategyCloseReason, type StrategyCommitContract, type StrategyEvent, type StrategyStatisticsModel, Sync, type SyncEvent, type SyncStatisticsModel, type TBrokerCtor, type TDumpInstanceCtor, type TIntervalFn, type TLogCtor, type TMarkdownBase, type TMemoryInstanceCtor, type TNotificationUtilsCtor, type TPersistBase, type TPersistBaseCtor, type TReportBase, type TStorageUtilsCtor, type TickEvent, type TrailingStopCommit, type TrailingStopCommitNotification, type TrailingTakeCommit, type TrailingTakeCommitNotification, type ValidationErrorNotification, Walker, type WalkerCompleteContract, type WalkerContract, type WalkerMetric, type SignalData$1 as WalkerSignalData, type WalkerStatisticsModel, addActionSchema, addExchangeSchema, addFrameSchema, addRiskSchema, addSizingSchema, addStrategySchema, addWalkerSchema, alignToInterval, checkCandles, commitActivateScheduled, commitAverageBuy, commitBreakeven, commitCancelScheduled, commitClosePending, commitPartialLoss, commitPartialLossCost, commitPartialProfit, commitPartialProfitCost, commitTrailingStop, commitTrailingStopCost, commitTrailingTake, commitTrailingTakeCost, dumpAgentAnswer, dumpError, dumpJson, dumpRecord, dumpTable, dumpText, emitters, formatPrice, formatQuantity, get, getActionSchema, getAggregatedTrades, getAveragePrice, getBacktestTimeframe, getBreakeven, getCandles, getColumns, getConfig, getContext, getDate, getDefaultColumns, getDefaultConfig, getEffectivePriceOpen, getExchangeSchema, getFrameSchema, getMode, getNextCandles, getOrderBook, getPendingSignal, getPositionCountdownMinutes, getPositionDrawdownMinutes, getPositionEffectivePrice, getPositionEntries, getPositionEntryOverlap, getPositionEstimateMinutes, getPositionHighestMaxDrawdownPnlCost, getPositionHighestMaxDrawdownPnlPercentage, getPositionHighestPnlCost, getPositionHighestPnlPercentage, getPositionHighestProfitBreakeven, getPositionHighestProfitDistancePnlCost, getPositionHighestProfitDistancePnlPercentage, getPositionHighestProfitMinutes, getPositionHighestProfitPrice, getPositionHighestProfitTimestamp, getPositionInvestedCost, getPositionInvestedCount, getPositionLevels, getPositionMaxDrawdownMinutes, getPositionMaxDrawdownPnlCost, getPositionMaxDrawdownPnlPercentage, getPositionMaxDrawdownPrice, getPositionMaxDrawdownTimestamp, getPositionPartialOverlap, getPositionPartials, getPositionPnlCost, getPositionPnlPercent, getRawCandles, getRiskSchema, getScheduledSignal, getSizingSchema, getStrategySchema, getSymbol, getTimestamp, getTotalClosed, getTotalCostClosed, getTotalPercentClosed, getWalkerSchema, hasNoPendingSignal, hasNoScheduledSignal, hasTradeContext, investedCostToPercent, backtest as lib, listExchangeSchema, listFrameSchema, listMemory, listRiskSchema, listSizingSchema, listStrategySchema, listWalkerSchema, listenActivePing, listenActivePingOnce, listenBacktestProgress, listenBreakevenAvailable, listenBreakevenAvailableOnce, listenDoneBacktest, listenDoneBacktestOnce, listenDoneLive, listenDoneLiveOnce, listenDoneWalker, listenDoneWalkerOnce, listenError, listenExit, listenHighestProfit, listenHighestProfitOnce, listenMaxDrawdown, listenMaxDrawdownOnce, listenPartialLossAvailable, listenPartialLossAvailableOnce, listenPartialProfitAvailable, listenPartialProfitAvailableOnce, listenPerformance, listenRisk, listenRiskOnce, listenSchedulePing, listenSchedulePingOnce, listenSignal, listenSignalBacktest, listenSignalBacktestOnce, listenSignalLive, listenSignalLiveOnce, listenSignalOnce, listenStrategyCommit, listenStrategyCommitOnce, listenSync, listenSyncOnce, listenValidation, listenWalker, listenWalkerComplete, listenWalkerOnce, listenWalkerProgress, overrideActionSchema, overrideExchangeSchema, overrideFrameSchema, overrideRiskSchema, overrideSizingSchema, overrideStrategySchema, overrideWalkerSchema, parseArgs, percentDiff, percentToCloseCost, percentValue, readMemory, removeMemory, roundTicks, runInMockContext, searchMemory, set, setColumns, setConfig, setLogger, shutdown, slPercentShiftToPrice, slPriceToPercentShift, stopStrategy, toProfitLossDto, tpPercentShiftToPrice, tpPriceToPercentShift, validate, validateCommonSignal, validatePendingSignal, validateScheduledSignal, validateSignal, waitForCandle, warmCandles, writeMemory };
+export { ActionBase, type ActivateScheduledCommit, type ActivateScheduledCommitNotification, type ActivePingContract, type AverageBuyCommit, type AverageBuyCommitNotification, Backtest, type BacktestStatisticsModel, Breakeven, type BreakevenAvailableNotification, type BreakevenCommit, type BreakevenCommitNotification, type BreakevenContract, type BreakevenData, type BreakevenEvent, type BreakevenStatisticsModel, Broker, type BrokerAverageBuyPayload, BrokerBase, type BrokerBreakevenPayload, type BrokerPartialLossPayload, type BrokerPartialProfitPayload, type BrokerSignalClosePayload, type BrokerSignalOpenPayload, type BrokerTrailingStopPayload, type BrokerTrailingTakePayload, Cache, type CancelScheduledCommit, type CancelScheduledCommitNotification, type CandleData, type CandleInterval, type ClosePendingCommit, type ClosePendingCommitNotification, type ColumnConfig, type ColumnModel, Constant, type CriticalErrorNotification, type DoneContract, Dump, type EntityId, Exchange, ExecutionContextService, type FrameInterval, type GlobalConfig, Heat, type HeatmapStatisticsModel, HighestProfit, type HighestProfitContract, type HighestProfitEvent, type HighestProfitStatisticsModel, type IActionSchema, type IActivateScheduledCommitRow, type IAggregatedTradeData, type IBidData, type IBreakevenCommitRow, type IBroker, type ICandleData, type ICommitRow, type IDumpContext, type IDumpInstance, type IExchangeSchema, type IFrameSchema, type IHeatmapRow, type ILog, type ILogEntry, type ILogger, type IMarkdownDumpOptions, type IMemoryInstance, type INotificationUtils, type IOrderBookData, type IPartialLossCommitRow, type IPartialProfitCommitRow, type IPersistBase, type IPositionSizeATRParams, type IPositionSizeFixedPercentageParams, type IPositionSizeKellyParams, type IPublicAction, type IPublicCandleData, type IPublicSignalRow, type IReportDumpOptions, type IRiskActivePosition, type IRiskCheckArgs, type IRiskSchema, type IRiskSignalRow, type IRiskValidation, type IRiskValidationFn, type IRiskValidationPayload, type IScheduledSignalCancelRow, type IScheduledSignalRow, type ISignalDto, type ISignalIntervalDto, type ISignalRow, type ISizingCalculateParams, type ISizingCalculateParamsATR, type ISizingCalculateParamsFixedPercentage, type ISizingCalculateParamsKelly, type ISizingParams, type ISizingParamsATR, type ISizingParamsFixedPercentage, type ISizingParamsKelly, type ISizingSchema, type ISizingSchemaATR, type ISizingSchemaFixedPercentage, type ISizingSchemaKelly, type IStorageSignalRow, type IStorageUtils, type IStrategyPnL, type IStrategyResult, type IStrategySchema, type IStrategyTickResult, type IStrategyTickResultActive, type IStrategyTickResultCancelled, type IStrategyTickResultClosed, type IStrategyTickResultIdle, type IStrategyTickResultOpened, type IStrategyTickResultScheduled, type IStrategyTickResultWaiting, type ITrailingStopCommitRow, type ITrailingTakeCommitRow, type IWalkerResults, type IWalkerSchema, type IWalkerStrategyResult, type InfoErrorNotification, Interval, type IntervalData, Live, type LiveStatisticsModel, Log, type LogData, Markdown, MarkdownFileBase, MarkdownFolderBase, type MarkdownName, MarkdownWriter, MaxDrawdown, type MaxDrawdownContract, type MaxDrawdownEvent, type MaxDrawdownStatisticsModel, type MeasureData, Memory, type MemoryData, type MessageModel, type MessageRole, type MessageToolCall, MethodContextService, type MetricStats, Notification, NotificationBacktest, type NotificationData, NotificationLive, type NotificationModel, Partial$1 as Partial, type PartialData, type PartialEvent, type PartialLossAvailableNotification, type PartialLossCommit, type PartialLossCommitNotification, type PartialLossContract, type PartialProfitAvailableNotification, type PartialProfitCommit, type PartialProfitCommitNotification, type PartialProfitContract, type PartialStatisticsModel, Performance, type PerformanceContract, type PerformanceMetricType, type PerformanceStatisticsModel, PersistBase, PersistBreakevenAdapter, PersistCandleAdapter, PersistIntervalAdapter, PersistLogAdapter, PersistMeasureAdapter, PersistMemoryAdapter, PersistNotificationAdapter, PersistPartialAdapter, PersistRiskAdapter, PersistScheduleAdapter, PersistSignalAdapter, PersistStorageAdapter, Position, PositionSize, type ProgressBacktestContract, type ProgressWalkerContract, Reflect, Report, ReportBase, type ReportName, ReportWriter, Risk, type RiskContract, type RiskData, type RiskEvent, type RiskRejectionNotification, type RiskStatisticsModel, Schedule, type ScheduleData, type SchedulePingContract, type ScheduleStatisticsModel, type ScheduledEvent, type SignalCancelledNotification, type SignalCloseContract, type SignalClosedNotification, type SignalData, type SignalInterval, type SignalOpenContract, type SignalOpenedNotification, type SignalScheduledNotification, type SignalSyncCloseNotification, type SignalSyncContract, type SignalSyncOpenNotification, Storage, StorageBacktest, type StorageData, StorageLive, Strategy, type StrategyActionType, type StrategyCancelReason, type StrategyCloseReason, type StrategyCommitContract, type StrategyEvent, type StrategyStatisticsModel, Sync, type SyncEvent, type SyncStatisticsModel, type TBrokerCtor, type TDumpInstanceCtor, type TLogCtor, type TMarkdownBase, type TMemoryInstanceCtor, type TNotificationUtilsCtor, type TPersistBase, type TPersistBaseCtor, type TReportBase, type TStorageUtilsCtor, type TickEvent, type TrailingStopCommit, type TrailingStopCommitNotification, type TrailingTakeCommit, type TrailingTakeCommitNotification, type ValidationErrorNotification, Walker, type WalkerCompleteContract, type WalkerContract, type WalkerMetric, type SignalData$1 as WalkerSignalData, type WalkerStatisticsModel, addActionSchema, addExchangeSchema, addFrameSchema, addRiskSchema, addSizingSchema, addStrategySchema, addWalkerSchema, alignToInterval, checkCandles, commitActivateScheduled, commitAverageBuy, commitBreakeven, commitCancelScheduled, commitClosePending, commitPartialLoss, commitPartialLossCost, commitPartialProfit, commitPartialProfitCost, commitTrailingStop, commitTrailingStopCost, commitTrailingTake, commitTrailingTakeCost, dumpAgentAnswer, dumpError, dumpJson, dumpRecord, dumpTable, dumpText, emitters, formatPrice, formatQuantity, get, getActionSchema, getAggregatedTrades, getAveragePrice, getBacktestTimeframe, getBreakeven, getCandles, getColumns, getConfig, getContext, getDate, getDefaultColumns, getDefaultConfig, getEffectivePriceOpen, getExchangeSchema, getFrameSchema, getMaxDrawdownDistancePnlCost, getMaxDrawdownDistancePnlPercentage, getMode, getNextCandles, getOrderBook, getPendingSignal, getPositionCountdownMinutes, getPositionDrawdownMinutes, getPositionEffectivePrice, getPositionEntries, getPositionEntryOverlap, getPositionEstimateMinutes, getPositionHighestMaxDrawdownPnlCost, getPositionHighestMaxDrawdownPnlPercentage, getPositionHighestPnlCost, getPositionHighestPnlPercentage, getPositionHighestProfitBreakeven, getPositionHighestProfitDistancePnlCost, getPositionHighestProfitDistancePnlPercentage, getPositionHighestProfitMinutes, getPositionHighestProfitPrice, getPositionHighestProfitTimestamp, getPositionInvestedCost, getPositionInvestedCount, getPositionLevels, getPositionMaxDrawdownMinutes, getPositionMaxDrawdownPnlCost, getPositionMaxDrawdownPnlPercentage, getPositionMaxDrawdownPrice, getPositionMaxDrawdownTimestamp, getPositionPartialOverlap, getPositionPartials, getPositionPnlCost, getPositionPnlPercent, getRawCandles, getRiskSchema, getScheduledSignal, getSizingSchema, getStrategySchema, getSymbol, getTimestamp, getTotalClosed, getTotalCostClosed, getTotalPercentClosed, getWalkerSchema, hasNoPendingSignal, hasNoScheduledSignal, hasTradeContext, investedCostToPercent, backtest as lib, listExchangeSchema, listFrameSchema, listMemory, listRiskSchema, listSizingSchema, listStrategySchema, listWalkerSchema, listenActivePing, listenActivePingOnce, listenBacktestProgress, listenBreakevenAvailable, listenBreakevenAvailableOnce, listenDoneBacktest, listenDoneBacktestOnce, listenDoneLive, listenDoneLiveOnce, listenDoneWalker, listenDoneWalkerOnce, listenError, listenExit, listenHighestProfit, listenHighestProfitOnce, listenMaxDrawdown, listenMaxDrawdownOnce, listenPartialLossAvailable, listenPartialLossAvailableOnce, listenPartialProfitAvailable, listenPartialProfitAvailableOnce, listenPerformance, listenRisk, listenRiskOnce, listenSchedulePing, listenSchedulePingOnce, listenSignal, listenSignalBacktest, listenSignalBacktestOnce, listenSignalLive, listenSignalLiveOnce, listenSignalOnce, listenStrategyCommit, listenStrategyCommitOnce, listenSync, listenSyncOnce, listenValidation, listenWalker, listenWalkerComplete, listenWalkerOnce, listenWalkerProgress, overrideActionSchema, overrideExchangeSchema, overrideFrameSchema, overrideRiskSchema, overrideSizingSchema, overrideStrategySchema, overrideWalkerSchema, parseArgs, percentDiff, percentToCloseCost, percentValue, readMemory, removeMemory, roundTicks, runInMockContext, searchMemory, set, setColumns, setConfig, setLogger, shutdown, slPercentShiftToPrice, slPriceToPercentShift, stopStrategy, toProfitLossDto, tpPercentShiftToPrice, tpPriceToPercentShift, validate, validateCommonSignal, validatePendingSignal, validateScheduledSignal, validateSignal, waitForCandle, warmCandles, writeMemory };