backtest-kit 6.10.0 → 6.12.0

package/build/index.mjs

@@ -4127,53 +4127,6 @@ const toProfitLossDto = (signal, priceClose) => {
     };
 };
 
-/**
- * Converts markdown content to plain text with minimal formatting
- * @param content - Markdown string to convert
- * @returns Plain text representation
- */
-const toPlainString = (content) => {
-    if (!content) {
-        return "";
-    }
-    let text = content;
-    // Remove code blocks
-    text = text.replace(/```[\s\S]*?```/g, "");
-    text = text.replace(/`([^`]+)`/g, "$1");
-    // Remove images
-    text = text.replace(/!\[([^\]]*)\]\([^)]+\)/g, "$1");
-    // Convert links to text only (keep link text, remove URL)
-    text = text.replace(/\[([^\]]+)\]\([^)]+\)/g, "$1");
-    // Remove headers (convert to plain text)
-    text = text.replace(/^#{1,6}\s+(.+)$/gm, "$1");
-    // Remove bold and italic markers
-    text = text.replace(/\*\*\*(.+?)\*\*\*/g, "$1");
-    text = text.replace(/\*\*(.+?)\*\*/g, "$1");
-    text = text.replace(/\*(.+?)\*/g, "$1");
-    text = text.replace(/___(.+?)___/g, "$1");
-    text = text.replace(/__(.+?)__/g, "$1");
-    text = text.replace(/_(.+?)_/g, "$1");
-    // Remove strikethrough
-    text = text.replace(/~~(.+?)~~/g, "$1");
-    // Convert lists to plain text with bullets
-    text = text.replace(/^\s*[-*+]\s+/gm, "• ");
-    text = text.replace(/^\s*\d+\.\s+/gm, "• ");
-    // Remove blockquotes
-    text = text.replace(/^\s*>\s+/gm, "");
-    // Remove horizontal rules
-    text = text.replace(/^(\*{3,}|-{3,}|_{3,})$/gm, "");
-    // Remove HTML tags
-    text = text.replace(/<[^>]+>/g, "");
-    // Remove excessive whitespace and normalize line breaks
-    text = text.replace(/\n[\s\n]*\n/g, "\n");
-    text = text.replace(/[ \t]+/g, " ");
-    // Remove all newline characters
-    text = text.replace(/\n/g, " ");
-    // Remove excessive spaces after newline removal
-    text = text.replace(/\s+/g, " ");
-    return text.trim();
-};
-
 /**
  * Returns the total closed state of a position using costBasisAtClose snapshots.
  *
@@ -4808,6 +4761,7 @@ const PROCESS_COMMIT_QUEUE_FN = async (self, currentPrice, timestamp) => {
                 originalPriceOpen: publicSignal.originalPriceOpen,
                 scheduledAt: publicSignal.scheduledAt,
                 pendingAt: publicSignal.pendingAt,
+                note: publicSignal.note,
             });
             continue;
         }
@@ -4835,6 +4789,7 @@ const PROCESS_COMMIT_QUEUE_FN = async (self, currentPrice, timestamp) => {
                 originalPriceOpen: publicSignal.originalPriceOpen,
                 scheduledAt: publicSignal.scheduledAt,
                 pendingAt: publicSignal.pendingAt,
+                note: publicSignal.note,
             });
             continue;
         }
@@ -4861,6 +4816,7 @@ const PROCESS_COMMIT_QUEUE_FN = async (self, currentPrice, timestamp) => {
                 originalPriceOpen: publicSignal.originalPriceOpen,
                 scheduledAt: publicSignal.scheduledAt,
                 pendingAt: publicSignal.pendingAt,
+                note: publicSignal.note,
             });
             continue;
         }
@@ -4888,6 +4844,7 @@ const PROCESS_COMMIT_QUEUE_FN = async (self, currentPrice, timestamp) => {
                 originalPriceOpen: publicSignal.originalPriceOpen,
                 scheduledAt: publicSignal.scheduledAt,
                 pendingAt: publicSignal.pendingAt,
+                note: publicSignal.note,
             });
             continue;
         }
@@ -4915,6 +4872,7 @@ const PROCESS_COMMIT_QUEUE_FN = async (self, currentPrice, timestamp) => {
                 originalPriceOpen: publicSignal.originalPriceOpen,
                 scheduledAt: publicSignal.scheduledAt,
                 pendingAt: publicSignal.pendingAt,
+                note: publicSignal.note,
             });
             continue;
         }
@@ -4944,6 +4902,7 @@ const PROCESS_COMMIT_QUEUE_FN = async (self, currentPrice, timestamp) => {
                 originalPriceOpen: publicSignal.originalPriceOpen,
                 scheduledAt: publicSignal.scheduledAt,
                 pendingAt: publicSignal.pendingAt,
+                note: publicSignal.note,
             });
             continue;
         }
@@ -5042,7 +5001,7 @@ const GET_SIGNAL_FN = trycatch(async (self) => {
     const currentPrice = await self.params.exchange.getAveragePrice(self.params.execution.context.symbol);
     const timeoutMs = GLOBAL_CONFIG.CC_MAX_SIGNAL_GENERATION_SECONDS * 1000;
     const signal = await Promise.race([
-        self.params.getSignal(self.params.execution.context.symbol, self.params.execution.context.when),
+        self.params.getSignal(self.params.execution.context.symbol, self.params.execution.context.when, currentPrice),
         sleep(timeoutMs).then(() => TIMEOUT_SYMBOL),
     ]);
     if (typeof signal === "symbol") {
@@ -5072,7 +5031,7 @@ const GET_SIGNAL_FN = trycatch(async (self) => {
                 cost: signal.cost || GLOBAL_CONFIG.CC_POSITION_ENTRY_COST,
                 priceOpen: signal.priceOpen, // Используем priceOpen из сигнала
                 position: signal.position,
-                note: toPlainString(signal.note),
+                note: signal.note || "",
                 priceTakeProfit: signal.priceTakeProfit,
                 priceStopLoss: signal.priceStopLoss,
                 minuteEstimatedTime: signal.minuteEstimatedTime ?? GLOBAL_CONFIG.CC_MAX_SIGNAL_LIFETIME_MINUTES,
@@ -5098,7 +5057,7 @@ const GET_SIGNAL_FN = trycatch(async (self) => {
             cost: signal.cost || GLOBAL_CONFIG.CC_POSITION_ENTRY_COST,
             priceOpen: signal.priceOpen,
             position: signal.position,
-            note: toPlainString(signal.note),
+            note: signal.note || "",
             priceTakeProfit: signal.priceTakeProfit,
             priceStopLoss: signal.priceStopLoss,
             minuteEstimatedTime: signal.minuteEstimatedTime ?? GLOBAL_CONFIG.CC_MAX_SIGNAL_LIFETIME_MINUTES,
@@ -5123,7 +5082,7 @@ const GET_SIGNAL_FN = trycatch(async (self) => {
         cost: signal.cost || GLOBAL_CONFIG.CC_POSITION_ENTRY_COST,
         priceOpen: currentPrice,
         ...structuredClone(signal),
-        note: toPlainString(signal.note),
+        note: signal.note || "",
         minuteEstimatedTime: signal.minuteEstimatedTime ?? GLOBAL_CONFIG.CC_MAX_SIGNAL_LIFETIME_MINUTES,
         symbol: self.params.execution.context.symbol,
         exchangeName: self.params.method.context.exchangeName,
@@ -5870,6 +5829,7 @@ const ACTIVATE_SCHEDULED_SIGNAL_FN = async (self, scheduled, activationTimestamp
             totalPartials: scheduled._partial?.length ?? 0,
             originalPriceOpen: scheduled.priceOpen,
             pnl: toProfitLossDto(scheduled, scheduled.priceOpen),
+            note: scheduled.note,
         });
         return null;
     }
@@ -6613,7 +6573,7 @@ const RETURN_IDLE_FN = async (self, currentPrice) => {
     await CALL_TICK_CALLBACKS_FN(self, self.params.execution.context.symbol, result, currentTime, self.params.execution.context.backtest);
     return result;
 };
-const CANCEL_SCHEDULED_SIGNAL_IN_BACKTEST_FN = async (self, scheduled, averagePrice, closeTimestamp, reason, cancelId) => {
+const CANCEL_SCHEDULED_SIGNAL_IN_BACKTEST_FN = async (self, scheduled, averagePrice, closeTimestamp, reason, cancelId, cancelNote) => {
     self.params.logger.info("ClientStrategy backtest scheduled signal cancelled", {
         symbol: self.params.execution.context.symbol,
         signalId: scheduled.id,
@@ -6638,6 +6598,7 @@ const CANCEL_SCHEDULED_SIGNAL_IN_BACKTEST_FN = async (self, scheduled, averagePr
             totalPartials: scheduled._partial?.length ?? 0,
             originalPriceOpen: scheduled.priceOpen,
             pnl: toProfitLossDto(scheduled, averagePrice),
+            note: cancelNote ?? scheduled.note,
         });
     }
     await CALL_CANCEL_CALLBACKS_FN(self, self.params.execution.context.symbol, scheduled, averagePrice, closeTimestamp, self.params.execution.context.backtest);
@@ -6716,6 +6677,7 @@ const ACTIVATE_SCHEDULED_SIGNAL_IN_BACKTEST_FN = async (self, scheduled, activat
             totalPartials: scheduled._partial?.length ?? 0,
             originalPriceOpen: scheduled.priceOpen,
             pnl: toProfitLossDto(scheduled, scheduled.priceOpen),
+            note: scheduled.note,
         });
         return false;
     }
@@ -6803,6 +6765,7 @@ const CLOSE_USER_PENDING_SIGNAL_IN_BACKTEST_FN = async (self, closedSignal, aver
         totalPartials: closedSignal._partial?.length ?? 0,
         originalPriceOpen: closedSignal.priceOpen,
         pnl: toProfitLossDto(closedSignal, averagePrice),
+        note: closedSignal.closeNote ?? closedSignal.note,
     });
     await CALL_CLOSE_CALLBACKS_FN(self, self.params.execution.context.symbol, closedSignal, averagePrice, closeTimestamp, self.params.execution.context.backtest);
     await CALL_PARTIAL_CLEAR_FN(self, self.params.execution.context.symbol, closedSignal, averagePrice, closeTimestamp, self.params.execution.context.backtest);
@@ -6849,7 +6812,8 @@ const PROCESS_SCHEDULED_SIGNAL_CANDLES_FN = async (self, scheduled, candles, fra
         if (self._cancelledSignal) {
             // Сигнал был отменен через cancel() в onSchedulePing
             const cancelId = self._cancelledSignal.cancelId;
-            const result = await CANCEL_SCHEDULED_SIGNAL_IN_BACKTEST_FN(self, scheduled, averagePrice, candle.timestamp, "user", cancelId);
+            const cancelNote = self._cancelledSignal.cancelNote;
+            const result = await CANCEL_SCHEDULED_SIGNAL_IN_BACKTEST_FN(self, scheduled, averagePrice, candle.timestamp, "user", cancelId, cancelNote);
             return { outcome: "cancelled", result };
         }
         // КРИТИЧНО: Проверяем был ли сигнал активирован пользователем через activateScheduled()
@@ -6903,6 +6867,7 @@ const PROCESS_SCHEDULED_SIGNAL_CANDLES_FN = async (self, scheduled, candles, fra
                     totalPartials: activatedSignal._partial?.length ?? 0,
                     originalPriceOpen: activatedSignal.priceOpen,
                     pnl: toProfitLossDto(activatedSignal, averagePrice),
+                    note: activatedSignal.activateNote ?? activatedSignal.note,
                 });
                 return { outcome: "pending" };
             }
@@ -6934,6 +6899,7 @@ const PROCESS_SCHEDULED_SIGNAL_CANDLES_FN = async (self, scheduled, candles, fra
                 pendingAt: publicSignalForCommit.pendingAt,
                 totalEntries: publicSignalForCommit.totalEntries,
                 totalPartials: publicSignalForCommit.totalPartials,
+                note: activatedSignal.activateNote ?? publicSignalForCommit.note,
             });
             await CALL_OPEN_CALLBACKS_FN(self, self.params.execution.context.symbol, pendingSignal, pendingSignal.priceOpen, candle.timestamp, self.params.execution.context.backtest);
             await CALL_BACKTEST_SCHEDULE_OPEN_FN(self, self.params.execution.context.symbol, pendingSignal, candle.timestamp, self.params.execution.context.backtest);
@@ -8054,6 +8020,44 @@ class ClientStrategy {
         const currentPnl = toProfitLossDto(this._pendingSignal, currentPrice);
         return Math.max(0, currentPnl.pnlCost - this._pendingSignal._fall.pnlCost);
     }
+    /**
+     * Returns the peak-to-trough PnL percentage distance between the position's highest profit and deepest drawdown.
+     *
+     * Measures the total swing from the stored `_peak.pnlPercentage` to the stored `_fall.pnlPercentage`.
+     * Computed as: max(0, peakPnlPercentage - fallPnlPercentage).
+     *
+     * Returns null if no pending signal exists.
+     *
+     * @param symbol - Trading pair symbol
+     * @param currentPrice - Current market price
+     * @returns Promise resolving to peak-to-trough PnL percentage distance (≥ 0) or null
+     */
+    async getMaxDrawdownDistancePnlPercentage(symbol, currentPrice) {
+        this.params.logger.debug("ClientStrategy getMaxDrawdownDistancePnlPercentage", { symbol, currentPrice });
+        if (!this._pendingSignal) {
+            return null;
+        }
+        return Math.max(0, this._pendingSignal._peak.pnlPercentage - this._pendingSignal._fall.pnlPercentage);
+    }
+    /**
+     * Returns the peak-to-trough PnL cost distance between the position's highest profit and deepest drawdown.
+     *
+     * Measures the total swing from the stored `_peak.pnlCost` to the stored `_fall.pnlCost`.
+     * Computed as: max(0, peakPnlCost - fallPnlCost).
+     *
+     * Returns null if no pending signal exists.
+     *
+     * @param symbol - Trading pair symbol
+     * @param currentPrice - Current market price
+     * @returns Promise resolving to peak-to-trough PnL cost distance (≥ 0) or null
+     */
+    async getMaxDrawdownDistancePnlCost(symbol, currentPrice) {
+        this.params.logger.debug("ClientStrategy getMaxDrawdownDistancePnlCost", { symbol, currentPrice });
+        if (!this._pendingSignal) {
+            return null;
+        }
+        return Math.max(0, this._pendingSignal._peak.pnlCost - this._pendingSignal._fall.pnlCost);
+    }
     /**
      * Performs a single tick of strategy execution.
      *
@@ -8118,6 +8122,7 @@ class ClientStrategy {
                 totalPartials: cancelledSignal._partial?.length ?? 0,
                 originalPriceOpen: cancelledSignal.priceOpen,
                 pnl: toProfitLossDto(cancelledSignal, currentPrice),
+                note: cancelledSignal.cancelNote ?? cancelledSignal.note,
             });
             // Call onCancel callback
             await CALL_CANCEL_CALLBACKS_FN(this, this.params.execution.context.symbol, cancelledSignal, currentPrice, currentTime, this.params.execution.context.backtest);
@@ -8171,6 +8176,7 @@ class ClientStrategy {
                 totalPartials: closedSignal._partial?.length ?? 0,
                 originalPriceOpen: closedSignal.priceOpen,
                 pnl: toProfitLossDto(closedSignal, currentPrice),
+                note: closedSignal.closeNote ?? closedSignal.note,
             });
             // Call onClose callback
             await CALL_CLOSE_CALLBACKS_FN(this, this.params.execution.context.symbol, closedSignal, currentPrice, currentTime, this.params.execution.context.backtest);
@@ -8252,6 +8258,7 @@ class ClientStrategy {
                     totalPartials: activatedSignal._partial?.length ?? 0,
                     originalPriceOpen: activatedSignal.priceOpen,
                     pnl: toProfitLossDto(activatedSignal, currentPrice),
+                    note: activatedSignal.activateNote ?? activatedSignal.note,
                 });
                 return await RETURN_IDLE_FN(this, currentPrice);
             }
@@ -8282,6 +8289,7 @@ class ClientStrategy {
                 pendingAt: publicSignalForCommit.pendingAt,
                 totalEntries: publicSignalForCommit.totalEntries,
                 totalPartials: publicSignalForCommit.totalPartials,
+                note: activatedSignal.activateNote ?? publicSignalForCommit.note,
             });
             // Call onOpen callback
             await CALL_OPEN_CALLBACKS_FN(this, this.params.execution.context.symbol, pendingSignal, currentPrice, currentTime, this.params.execution.context.backtest);
@@ -8417,6 +8425,7 @@ class ClientStrategy {
                 totalPartials: cancelledSignal._partial?.length ?? 0,
                 originalPriceOpen: cancelledSignal.priceOpen,
                 pnl: toProfitLossDto(cancelledSignal, currentPrice),
+                note: cancelledSignal.cancelNote ?? cancelledSignal.note,
             });
             await CALL_CANCEL_CALLBACKS_FN(this, this.params.execution.context.symbol, cancelledSignal, currentPrice, closeTimestamp, this.params.execution.context.backtest);
             const cancelledResult = {
@@ -8471,6 +8480,7 @@ class ClientStrategy {
                 totalPartials: closedSignal._partial?.length ?? 0,
                 originalPriceOpen: closedSignal.priceOpen,
                 pnl: toProfitLossDto(closedSignal, currentPrice),
+                note: closedSignal.closeNote ?? closedSignal.note,
             });
             await CALL_CLOSE_CALLBACKS_FN(this, this.params.execution.context.symbol, closedSignal, currentPrice, closeTimestamp, this.params.execution.context.backtest);
             // КРИТИЧНО: Очищаем состояние ClientPartial при закрытии позиции
@@ -8654,7 +8664,8 @@ class ClientStrategy {
      * // Strategy continues, can generate new signals
      * ```
      */
-    async cancelScheduled(symbol, backtest, cancelId) {
+    async cancelScheduled(symbol, backtest, payload) {
+        const cancelId = payload.id;
         this.params.logger.debug("ClientStrategy cancelScheduled", {
             symbol,
             hasScheduledSignal: this._scheduledSignal !== null,
@@ -8666,6 +8677,7 @@ class ClientStrategy {
         if (this._scheduledSignal) {
             this._cancelledSignal = Object.assign({}, this._scheduledSignal, {
                 cancelId,
+                cancelNote: payload.note,
             });
             this._scheduledSignal = null;
         }
@@ -8697,7 +8709,8 @@ class ClientStrategy {
      * // Scheduled signal becomes pending signal immediately
      * ```
      */
-    async activateScheduled(symbol, backtest, activateId) {
+    async activateScheduled(symbol, backtest, payload) {
+        const activateId = payload.id;
         this.params.logger.debug("ClientStrategy activateScheduled", {
             symbol,
             hasScheduledSignal: this._scheduledSignal !== null,
@@ -8715,6 +8728,7 @@ class ClientStrategy {
         if (this._scheduledSignal) {
             this._activatedSignal = Object.assign({}, this._scheduledSignal, {
                 activateId,
+                activateNote: payload.note,
             });
             this._scheduledSignal = null;
         }
@@ -8746,7 +8760,8 @@ class ClientStrategy {
      * // Strategy continues, can generate new signals
      * ```
      */
-    async closePending(symbol, backtest, closeId) {
+    async closePending(symbol, backtest, payload) {
+        const closeId = payload.id;
         this.params.logger.debug("ClientStrategy closePending", {
             symbol,
             hasPendingSignal: this._pendingSignal !== null,
@@ -8757,6 +8772,7 @@ class ClientStrategy {
         if (this._pendingSignal) {
             this._closedSignal = Object.assign({}, this._pendingSignal, {
                 closeId,
+                closeNote: payload.note,
             });
             this._pendingSignal = null;
         }
@@ -10020,6 +10036,8 @@ class MergeRisk {
     }
 }
 
+/** Default interval for strategies that do not specify one */
+const STRATEGY_DEFAULT_INTERVAL = "1m";
 /**
  * If syncSubject listener or any registered action throws, it means the signal was not properly synchronized
  * to the exchange (e.g. limit order failed to fill).
@@ -10405,7 +10423,7 @@ class StrategyConnectionService {
          * @returns Configured ClientStrategy instance
          */
         this.getStrategy = memoize(([symbol, strategyName, exchangeName, frameName, backtest]) => CREATE_KEY_FN$t(symbol, strategyName, exchangeName, frameName, backtest), (symbol, strategyName, exchangeName, frameName, backtest) => {
-            const { riskName = "", riskList = [], getSignal, interval, callbacks, } = this.strategySchemaService.get(strategyName);
+            const { riskName = "", riskList = [], getSignal, interval = STRATEGY_DEFAULT_INTERVAL, callbacks, } = this.strategySchemaService.get(strategyName);
             return new ClientStrategy({
                 symbol,
                 interval,
@@ -11245,6 +11263,48 @@ class StrategyConnectionService {
             const currentPrice = await this.priceMetaService.getCurrentPrice(symbol, context, backtest);
             return await strategy.getPositionHighestMaxDrawdownPnlCost(symbol, currentPrice);
         };
+        /**
+         * 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
+         */
+        this.getMaxDrawdownDistancePnlPercentage = async (backtest, symbol, context) => {
+            this.loggerService.log("strategyConnectionService getMaxDrawdownDistancePnlPercentage", {
+                symbol,
+                context,
+            });
+            const strategy = this.getStrategy(symbol, context.strategyName, context.exchangeName, context.frameName, backtest);
+            const currentPrice = await this.priceMetaService.getCurrentPrice(symbol, context, backtest);
+            return await strategy.getMaxDrawdownDistancePnlPercentage(symbol, currentPrice);
+        };
+        /**
+         * 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
+         */
+        this.getMaxDrawdownDistancePnlCost = async (backtest, symbol, context) => {
+            this.loggerService.log("strategyConnectionService getMaxDrawdownDistancePnlCost", {
+                symbol,
+                context,
+            });
+            const strategy = this.getStrategy(symbol, context.strategyName, context.exchangeName, context.frameName, backtest);
+            const currentPrice = await this.priceMetaService.getCurrentPrice(symbol, context, backtest);
+            return await strategy.getMaxDrawdownDistancePnlCost(symbol, currentPrice);
+        };
         /**
          * Disposes the ClientStrategy instance for the given context.
          *
@@ -11304,17 +11364,17 @@ class StrategyConnectionService {
          * @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
          */
-        this.cancelScheduled = async (backtest, symbol, context, cancelId) => {
+        this.cancelScheduled = async (backtest, symbol, context, payload = {}) => {
             this.loggerService.log("strategyConnectionService cancelScheduled", {
                 symbol,
                 context,
-                cancelId,
+                payload,
             });
             const strategy = this.getStrategy(symbol, context.strategyName, context.exchangeName, context.frameName, backtest);
-            await strategy.cancelScheduled(symbol, backtest, cancelId);
+            await strategy.cancelScheduled(symbol, backtest, payload);
         };
         /**
          * Closes the pending signal without stopping the strategy.
@@ -11329,17 +11389,17 @@ class StrategyConnectionService {
          * @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
          */
-        this.closePending = async (backtest, symbol, context, closeId) => {
+        this.closePending = async (backtest, symbol, context, payload = {}) => {
             this.loggerService.log("strategyConnectionService closePending", {
                 symbol,
                 context,
-                closeId,
+                payload,
             });
             const strategy = this.getStrategy(symbol, context.strategyName, context.exchangeName, context.frameName, backtest);
-            await strategy.closePending(symbol, backtest, closeId);
+            await strategy.closePending(symbol, backtest, payload);
         };
         /**
          * Checks whether `partialProfit` would succeed without executing it.
@@ -11618,7 +11678,7 @@ class StrategyConnectionService {
          * @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
@@ -11628,19 +11688,19 @@ class StrategyConnectionService {
          *   false,
          *   "BTCUSDT",
          *   { strategyName: "my-strategy", exchangeName: "binance", frameName: "" },
-         *   "manual-activation"
+         *   { id: "manual-activation" }
          * );
          * ```
          */
-        this.activateScheduled = async (backtest, symbol, context, activateId) => {
+        this.activateScheduled = async (backtest, symbol, context, payload = {}) => {
             this.loggerService.log("strategyConnectionService activateScheduled", {
                 symbol,
                 context,
                 backtest,
-                activateId,
+                payload,
             });
             const strategy = this.getStrategy(symbol, context.strategyName, context.exchangeName, context.frameName, backtest);
-            return await strategy.activateScheduled(symbol, backtest, activateId);
+            return await strategy.activateScheduled(symbol, backtest, payload);
         };
         /**
          * Checks whether `averageBuy` would succeed without executing it.
@@ -14675,18 +14735,18 @@ class StrategyCoreService {
          * @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
          */
-        this.cancelScheduled = async (backtest, symbol, context, cancelId) => {
+        this.cancelScheduled = async (backtest, symbol, context, payload = {}) => {
             this.loggerService.log("strategyCoreService cancelScheduled", {
                 symbol,
                 context,
                 backtest,
-                cancelId,
+                payload,
             });
             await this.validate(context);
-            return await this.strategyConnectionService.cancelScheduled(backtest, symbol, context, cancelId);
+            return await this.strategyConnectionService.cancelScheduled(backtest, symbol, context, payload);
         };
         /**
          * Closes the pending signal without stopping the strategy.
@@ -14702,18 +14762,18 @@ class StrategyCoreService {
          * @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
          */
-        this.closePending = async (backtest, symbol, context, closeId) => {
+        this.closePending = async (backtest, symbol, context, payload = {}) => {
             this.loggerService.log("strategyCoreService closePending", {
                 symbol,
                 context,
                 backtest,
-                closeId,
+                payload,
             });
             await this.validate(context);
-            return await this.strategyConnectionService.closePending(backtest, symbol, context, closeId);
+            return await this.strategyConnectionService.closePending(backtest, symbol, context, payload);
         };
         /**
          * Disposes the ClientStrategy instance for the given context.
@@ -15058,7 +15118,7 @@ class StrategyCoreService {
          * @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
@@ -15068,19 +15128,19 @@ class StrategyCoreService {
          *   false,
          *   "BTCUSDT",
          *   { strategyName: "my-strategy", exchangeName: "binance", frameName: "" },
-         *   "manual-activation"
+         *   { id: "manual-activation" }
          * );
          * ```
          */
-        this.activateScheduled = async (backtest, symbol, context, activateId) => {
+        this.activateScheduled = async (backtest, symbol, context, payload = {}) => {
             this.loggerService.log("strategyCoreService activateScheduled", {
                 symbol,
                 context,
                 backtest,
-                activateId,
+                payload,
             });
             await this.validate(context);
-            return await this.strategyConnectionService.activateScheduled(backtest, symbol, context, activateId);
+            return await this.strategyConnectionService.activateScheduled(backtest, symbol, context, payload);
         };
         /**
          * Checks whether `averageBuy` would succeed without executing it.
@@ -15482,6 +15542,44 @@ class StrategyCoreService {
             await this.validate(context);
             return await this.strategyConnectionService.getPositionHighestMaxDrawdownPnlCost(backtest, symbol, context);
         };
+        /**
+         * 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
+         */
+        this.getMaxDrawdownDistancePnlPercentage = async (backtest, symbol, context) => {
+            this.loggerService.log("strategyCoreService getMaxDrawdownDistancePnlPercentage", {
+                symbol,
+                context,
+            });
+            await this.validate(context);
+            return await this.strategyConnectionService.getMaxDrawdownDistancePnlPercentage(backtest, symbol, context);
+        };
+        /**
+         * 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
+         */
+        this.getMaxDrawdownDistancePnlCost = async (backtest, symbol, context) => {
+            this.loggerService.log("strategyCoreService getMaxDrawdownDistancePnlCost", {
+                symbol,
+                context,
+            });
+            await this.validate(context);
+            return await this.strategyConnectionService.getMaxDrawdownDistancePnlCost(backtest, symbol, context);
+        };
     }
 }
 
@@ -16124,8 +16222,8 @@ class StrategySchemaService {
             if (strategySchema.actions?.some((value) => typeof value !== "string")) {
                 throw new Error(`strategy schema validation failed: invalid actions for strategyName=${strategySchema.strategyName} actions=[${strategySchema.actions}]`);
             }
-            if (typeof strategySchema.interval !== "string") {
-                throw new Error(`strategy schema validation failed: missing interval for strategyName=${strategySchema.strategyName}`);
+            if (strategySchema.interval && typeof strategySchema.interval !== "string") {
+                throw new Error(`strategy schema validation failed: invalid interval for strategyName=${strategySchema.strategyName}`);
             }
             if (typeof strategySchema.getSignal !== "function") {
                 throw new Error(`strategy schema validation failed: missing getSignal for strategyName=${strategySchema.strategyName}`);
@@ -18071,6 +18169,53 @@ class WalkerCommandService {
     }
 }
 
+/**
+ * Converts markdown content to plain text with minimal formatting
+ * @param content - Markdown string to convert
+ * @returns Plain text representation
+ */
+const toPlainString = (content) => {
+    if (!content) {
+        return "";
+    }
+    let text = content;
+    // Remove code blocks
+    text = text.replace(/```[\s\S]*?```/g, "");
+    text = text.replace(/`([^`]+)`/g, "$1");
+    // Remove images
+    text = text.replace(/!\[([^\]]*)\]\([^)]+\)/g, "$1");
+    // Convert links to text only (keep link text, remove URL)
+    text = text.replace(/\[([^\]]+)\]\([^)]+\)/g, "$1");
+    // Remove headers (convert to plain text)
+    text = text.replace(/^#{1,6}\s+(.+)$/gm, "$1");
+    // Remove bold and italic markers
+    text = text.replace(/\*\*\*(.+?)\*\*\*/g, "$1");
+    text = text.replace(/\*\*(.+?)\*\*/g, "$1");
+    text = text.replace(/\*(.+?)\*/g, "$1");
+    text = text.replace(/___(.+?)___/g, "$1");
+    text = text.replace(/__(.+?)__/g, "$1");
+    text = text.replace(/_(.+?)_/g, "$1");
+    // Remove strikethrough
+    text = text.replace(/~~(.+?)~~/g, "$1");
+    // Convert lists to plain text with bullets
+    text = text.replace(/^\s*[-*+]\s+/gm, "• ");
+    text = text.replace(/^\s*\d+\.\s+/gm, "• ");
+    // Remove blockquotes
+    text = text.replace(/^\s*>\s+/gm, "");
+    // Remove horizontal rules
+    text = text.replace(/^(\*{3,}|-{3,}|_{3,})$/gm, "");
+    // Remove HTML tags
+    text = text.replace(/<[^>]+>/g, "");
+    // Remove excessive whitespace and normalize line breaks
+    text = text.replace(/\n[\s\n]*\n/g, "\n");
+    text = text.replace(/[ \t]+/g, " ");
+    // Remove all newline characters
+    text = text.replace(/\n/g, " ");
+    // Remove excessive spaces after newline removal
+    text = text.replace(/\s+/g, " ");
+    return text.trim();
+};
+
 /**
  * Column configuration for backtest markdown reports.
  *
@@ -18746,7 +18891,7 @@ const partial_columns = [
     {
         key: "note",
         label: "Note",
-        format: (data) => data.note || "",
+        format: (data) => toPlainString(data.note ?? "N/A"),
         isVisible: () => GLOBAL_CONFIG.CC_REPORT_SHOW_SIGNAL_NOTE,
     },
     {
@@ -18906,7 +19051,7 @@ const breakeven_columns = [
     {
         key: "note",
         label: "Note",
-        format: (data) => data.note || "",
+        format: (data) => toPlainString(data.note ?? "N/A"),
         isVisible: () => GLOBAL_CONFIG.CC_REPORT_SHOW_SIGNAL_NOTE,
     },
     {
@@ -29034,7 +29179,7 @@ class StrategyReportService {
         /**
          * Logs a cancel-scheduled event when a scheduled signal is cancelled.
          */
-        this.cancelScheduled = async (symbol, isBacktest, context, timestamp, signalId, pnl, totalPartials, cancelId) => {
+        this.cancelScheduled = async (symbol, isBacktest, context, timestamp, signalId, pnl, totalPartials, cancelId, note) => {
             this.loggerService.log("strategyReportService cancelScheduled", {
                 symbol,
                 isBacktest,
@@ -29047,6 +29192,7 @@ class StrategyReportService {
             await ReportWriter.writeData("strategy", {
                 action: "cancel-scheduled",
                 cancelId,
+                note,
                 symbol,
                 timestamp,
                 createdAt,
@@ -29068,7 +29214,7 @@ class StrategyReportService {
         /**
          * Logs a close-pending event when a pending signal is closed.
          */
-        this.closePending = async (symbol, isBacktest, context, timestamp, signalId, pnl, totalPartials, closeId) => {
+        this.closePending = async (symbol, isBacktest, context, timestamp, signalId, pnl, totalPartials, closeId, note) => {
             this.loggerService.log("strategyReportService closePending", {
                 symbol,
                 isBacktest,
@@ -29081,6 +29227,7 @@ class StrategyReportService {
             await ReportWriter.writeData("strategy", {
                 action: "close-pending",
                 closeId,
+                note,
                 symbol,
                 timestamp,
                 createdAt,
@@ -29330,7 +29477,7 @@ class StrategyReportService {
         /**
          * Logs an activate-scheduled event when a scheduled signal is activated early.
          */
-        this.activateScheduled = async (symbol, currentPrice, isBacktest, context, timestamp, signalId, pnl, totalPartials, position, priceOpen, priceTakeProfit, priceStopLoss, originalPriceTakeProfit, originalPriceStopLoss, scheduledAt, pendingAt, totalEntries, originalPriceOpen, activateId) => {
+        this.activateScheduled = async (symbol, currentPrice, isBacktest, context, timestamp, signalId, pnl, totalPartials, position, priceOpen, priceTakeProfit, priceStopLoss, originalPriceTakeProfit, originalPriceStopLoss, scheduledAt, pendingAt, totalEntries, originalPriceOpen, activateId, note) => {
             this.loggerService.log("strategyReportService activateScheduled", {
                 symbol,
                 currentPrice,
@@ -29344,6 +29491,7 @@ class StrategyReportService {
             await ReportWriter.writeData("strategy", {
                 action: "activate-scheduled",
                 activateId,
+                note,
                 currentPrice,
                 symbol,
                 timestamp,
@@ -29437,14 +29585,14 @@ class StrategyReportService {
                 exchangeName: event.exchangeName,
                 frameName: event.frameName,
                 strategyName: event.strategyName,
-            }, event.timestamp, event.signalId, event.pnl, event.totalPartials, event.cancelId));
+            }, event.timestamp, event.signalId, event.pnl, event.totalPartials, event.cancelId, event.note));
             const unClosePending = strategyCommitSubject
                 .filter(({ action }) => action === "close-pending")
                 .connect(async (event) => await this.closePending(event.symbol, event.backtest, {
                 exchangeName: event.exchangeName,
                 frameName: event.frameName,
                 strategyName: event.strategyName,
-            }, event.timestamp, event.signalId, event.pnl, event.totalPartials, event.closeId));
+            }, event.timestamp, event.signalId, event.pnl, event.totalPartials, event.closeId, event.note));
             const unPartialProfit = strategyCommitSubject
                 .filter(({ action }) => action === "partial-profit")
                 .connect(async (event) => await this.partialProfit(event.symbol, event.percentToClose, event.currentPrice, event.backtest, {
@@ -29486,7 +29634,7 @@ class StrategyReportService {
                 exchangeName: event.exchangeName,
                 frameName: event.frameName,
                 strategyName: event.strategyName,
-            }, event.timestamp, event.signalId, event.pnl, event.totalPartials, event.position, event.priceOpen, event.priceTakeProfit, event.priceStopLoss, event.originalPriceTakeProfit, event.originalPriceStopLoss, event.scheduledAt, event.pendingAt, event.totalEntries, event.originalPriceOpen, event.activateId));
+            }, event.timestamp, event.signalId, event.pnl, event.totalPartials, event.position, event.priceOpen, event.priceTakeProfit, event.priceStopLoss, event.originalPriceTakeProfit, event.originalPriceStopLoss, event.scheduledAt, event.pendingAt, event.totalEntries, event.originalPriceOpen, event.activateId, event.note));
             const unAverageBuy = strategyCommitSubject
                 .filter(({ action }) => action === "average-buy")
                 .connect(async (event) => await this.averageBuy(event.symbol, event.currentPrice, event.effectivePriceOpen, event.totalEntries, event.backtest, {
@@ -30025,8 +30173,9 @@ 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
          */
-        this.cancelScheduled = async (symbol, isBacktest, context, timestamp, signalId, pnl, cancelId) => {
+        this.cancelScheduled = async (symbol, isBacktest, context, timestamp, signalId, pnl, cancelId, note) => {
             this.loggerService.log("strategyMarkdownService cancelScheduled", {
                 symbol,
                 isBacktest,
@@ -30047,6 +30196,7 @@ class StrategyMarkdownService {
                 action: "cancel-scheduled",
                 pnl,
                 cancelId,
+                note,
                 createdAt,
                 backtest: isBacktest,
             });
@@ -30059,8 +30209,9 @@ 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
          */
-        this.closePending = async (symbol, isBacktest, context, timestamp, signalId, pnl, closeId) => {
+        this.closePending = async (symbol, isBacktest, context, timestamp, signalId, pnl, closeId, note) => {
             this.loggerService.log("strategyMarkdownService closePending", {
                 symbol,
                 isBacktest,
@@ -30081,6 +30232,7 @@ class StrategyMarkdownService {
                 action: "close-pending",
                 pnl,
                 closeId,
+                note,
                 createdAt,
                 backtest: isBacktest,
             });
@@ -30379,8 +30531,9 @@ 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
          */
-        this.activateScheduled = async (symbol, currentPrice, isBacktest, context, timestamp, signalId, pnl, totalPartials, position, priceOpen, priceTakeProfit, priceStopLoss, originalPriceTakeProfit, originalPriceStopLoss, scheduledAt, pendingAt, totalEntries, originalPriceOpen, activateId) => {
+        this.activateScheduled = async (symbol, currentPrice, isBacktest, context, timestamp, signalId, pnl, totalPartials, position, priceOpen, priceTakeProfit, priceStopLoss, originalPriceTakeProfit, originalPriceStopLoss, scheduledAt, pendingAt, totalEntries, originalPriceOpen, activateId, note) => {
             this.loggerService.log("strategyMarkdownService activateScheduled", {
                 symbol,
                 currentPrice,
@@ -30403,6 +30556,7 @@ class StrategyMarkdownService {
                 pnl,
                 totalPartials,
                 activateId,
+                note,
                 currentPrice,
                 createdAt,
                 backtest: isBacktest,
@@ -30607,14 +30761,14 @@ class StrategyMarkdownService {
                 exchangeName: event.exchangeName,
                 frameName: event.frameName,
                 strategyName: event.strategyName,
-            }, event.timestamp, event.signalId, event.pnl, event.cancelId));
+            }, event.timestamp, event.signalId, event.pnl, event.cancelId, event.note));
             const unClosePending = strategyCommitSubject
                 .filter(({ action }) => action === "close-pending")
                 .connect(async (event) => await this.closePending(event.symbol, event.backtest, {
                 exchangeName: event.exchangeName,
                 frameName: event.frameName,
                 strategyName: event.strategyName,
-            }, event.timestamp, event.signalId, event.pnl, event.closeId));
+            }, event.timestamp, event.signalId, event.pnl, event.closeId, event.note));
             const unPartialProfit = strategyCommitSubject
                 .filter(({ action }) => action === "partial-profit")
                 .connect(async (event) => await this.partialProfit(event.symbol, event.percentToClose, event.currentPrice, event.backtest, {
@@ -30656,7 +30810,7 @@ class StrategyMarkdownService {
                 exchangeName: event.exchangeName,
                 frameName: event.frameName,
                 strategyName: event.strategyName,
-            }, event.timestamp, event.signalId, event.pnl, event.totalPartials, event.position, event.priceOpen, event.priceTakeProfit, event.priceStopLoss, event.originalPriceTakeProfit, event.originalPriceStopLoss, event.scheduledAt, event.pendingAt, event.totalEntries, event.originalPriceOpen, event.activateId));
+            }, event.timestamp, event.signalId, event.pnl, event.totalPartials, event.position, event.priceOpen, event.priceTakeProfit, event.priceStopLoss, event.originalPriceTakeProfit, event.originalPriceStopLoss, event.scheduledAt, event.pendingAt, event.totalEntries, event.originalPriceOpen, event.activateId, event.note));
             const unAverageBuy = strategyCommitSubject
                 .filter(({ action }) => action === "average-buy")
                 .connect(async (event) => await this.averageBuy(event.symbol, event.currentPrice, event.effectivePriceOpen, event.totalEntries, event.backtest, {
@@ -35141,6 +35295,8 @@ const GET_POSITION_HIGHEST_PROFIT_DISTANCE_PNL_PERCENTAGE_METHOD_NAME = "strateg
 const GET_POSITION_HIGHEST_PROFIT_DISTANCE_PNL_COST_METHOD_NAME = "strategy.getPositionHighestProfitDistancePnlCost";
 const GET_POSITION_HIGHEST_MAX_DRAWDOWN_PNL_PERCENTAGE_METHOD_NAME = "strategy.getPositionHighestMaxDrawdownPnlPercentage";
 const GET_POSITION_HIGHEST_MAX_DRAWDOWN_PNL_COST_METHOD_NAME = "strategy.getPositionHighestMaxDrawdownPnlCost";
+const GET_MAX_DRAWDOWN_DISTANCE_PNL_PERCENTAGE_METHOD_NAME = "strategy.getMaxDrawdownDistancePnlPercentage";
+const GET_MAX_DRAWDOWN_DISTANCE_PNL_COST_METHOD_NAME = "strategy.getMaxDrawdownDistancePnlCost";
 const GET_POSITION_ENTRY_OVERLAP_METHOD_NAME = "strategy.getPositionEntryOverlap";
 const GET_POSITION_PARTIAL_OVERLAP_METHOD_NAME = "strategy.getPositionPartialOverlap";
 const HAS_NO_PENDING_SIGNAL_METHOD_NAME = "strategy.hasNoPendingSignal";
@@ -35156,7 +35312,7 @@ const HAS_NO_SCHEDULED_SIGNAL_METHOD_NAME = "strategy.hasNoScheduledSignal";
  *
  * @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
@@ -35164,13 +35320,13 @@ const HAS_NO_SCHEDULED_SIGNAL_METHOD_NAME = "strategy.hasNoScheduledSignal";
  * import { commitCancelScheduled } from "backtest-kit";
  *
  * // Cancel scheduled signal with custom ID
- * await commitCancelScheduled("BTCUSDT", "manual-cancel-001");
+ * await commitCancelScheduled("BTCUSDT", { id: "manual-cancel-001" });
  * ```
  */
-async function commitCancelScheduled(symbol, cancelId) {
+async function commitCancelScheduled(symbol, payload = {}) {
     backtest.loggerService.info(CANCEL_SCHEDULED_METHOD_NAME, {
         symbol,
-        cancelId,
+        payload,
     });
     if (!ExecutionContextService.hasContext()) {
         throw new Error("commitCancelScheduled requires an execution context");
@@ -35180,7 +35336,7 @@ async function commitCancelScheduled(symbol, cancelId) {
     }
     const { backtest: isBacktest } = backtest.executionContextService.context;
     const { exchangeName, frameName, strategyName } = backtest.methodContextService.context;
-    await backtest.strategyCoreService.cancelScheduled(isBacktest, symbol, { exchangeName, frameName, strategyName }, cancelId);
+    await backtest.strategyCoreService.cancelScheduled(isBacktest, symbol, { exchangeName, frameName, strategyName }, payload);
 }
 /**
  * Closes the pending signal without stopping the strategy.
@@ -35192,7 +35348,7 @@ async function commitCancelScheduled(symbol, cancelId) {
  * 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
@@ -35200,13 +35356,13 @@ async function commitCancelScheduled(symbol, cancelId) {
  * import { commitClosePending } from "backtest-kit";
  *
  * // Close pending signal with custom ID
- * await commitClosePending("BTCUSDT", "manual-close-001");
+ * await commitClosePending("BTCUSDT", { id: "manual-close-001" });
  * ```
  */
-async function commitClosePending(symbol, closeId) {
+async function commitClosePending(symbol, payload = {}) {
     backtest.loggerService.info(CLOSE_PENDING_METHOD_NAME, {
         symbol,
-        closeId,
+        payload,
     });
     if (!ExecutionContextService.hasContext()) {
         throw new Error("commitClosePending requires an execution context");
@@ -35216,7 +35372,7 @@ async function commitClosePending(symbol, closeId) {
     }
     const { backtest: isBacktest } = backtest.executionContextService.context;
     const { exchangeName, frameName, strategyName } = backtest.methodContextService.context;
-    await backtest.strategyCoreService.closePending(isBacktest, symbol, { exchangeName, frameName, strategyName }, closeId);
+    await backtest.strategyCoreService.closePending(isBacktest, symbol, { exchangeName, frameName, strategyName }, payload);
 }
 /**
  * Executes partial close at profit level (moving toward TP).
@@ -35679,7 +35835,7 @@ async function commitBreakeven(symbol) {
  * 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
@@ -35687,13 +35843,13 @@ async function commitBreakeven(symbol) {
  * 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" });
  * ```
  */
-async function commitActivateScheduled(symbol, activateId) {
+async function commitActivateScheduled(symbol, payload = {}) {
     backtest.loggerService.info(ACTIVATE_SCHEDULED_METHOD_NAME, {
         symbol,
-        activateId,
+        payload,
     });
     if (!ExecutionContextService.hasContext()) {
         throw new Error("commitActivateScheduled requires an execution context");
@@ -35703,7 +35859,7 @@ async function commitActivateScheduled(symbol, activateId) {
     }
     const { backtest: isBacktest } = backtest.executionContextService.context;
     const { exchangeName, frameName, strategyName } = backtest.methodContextService.context;
-    await backtest.strategyCoreService.activateScheduled(isBacktest, symbol, { exchangeName, frameName, strategyName }, activateId);
+    await backtest.strategyCoreService.activateScheduled(isBacktest, symbol, { exchangeName, frameName, strategyName }, payload);
 }
 /**
  * Adds a new DCA entry to the active pending signal.
@@ -36891,6 +37047,64 @@ async function getPositionHighestMaxDrawdownPnlCost(symbol) {
     const { exchangeName, frameName, strategyName } = backtest.methodContextService.context;
     return await backtest.strategyCoreService.getPositionHighestMaxDrawdownPnlCost(isBacktest, symbol, { exchangeName, frameName, strategyName });
 }
+/**
+ * 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)
+ * ```
+ */
+async function getMaxDrawdownDistancePnlPercentage(symbol) {
+    backtest.loggerService.info(GET_MAX_DRAWDOWN_DISTANCE_PNL_PERCENTAGE_METHOD_NAME, { symbol });
+    if (!ExecutionContextService.hasContext()) {
+        throw new Error("getMaxDrawdownDistancePnlPercentage requires an execution context");
+    }
+    if (!MethodContextService.hasContext()) {
+        throw new Error("getMaxDrawdownDistancePnlPercentage requires a method context");
+    }
+    const { backtest: isBacktest } = backtest.executionContextService.context;
+    const { exchangeName, frameName, strategyName } = backtest.methodContextService.context;
+    return await backtest.strategyCoreService.getMaxDrawdownDistancePnlPercentage(isBacktest, symbol, { exchangeName, frameName, strategyName });
+}
+/**
+ * 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)
+ * ```
+ */
+async function getMaxDrawdownDistancePnlCost(symbol) {
+    backtest.loggerService.info(GET_MAX_DRAWDOWN_DISTANCE_PNL_COST_METHOD_NAME, { symbol });
+    if (!ExecutionContextService.hasContext()) {
+        throw new Error("getMaxDrawdownDistancePnlCost requires an execution context");
+    }
+    if (!MethodContextService.hasContext()) {
+        throw new Error("getMaxDrawdownDistancePnlCost requires a method context");
+    }
+    const { backtest: isBacktest } = backtest.executionContextService.context;
+    const { exchangeName, frameName, strategyName } = backtest.methodContextService.context;
+    return await backtest.strategyCoreService.getMaxDrawdownDistancePnlCost(isBacktest, symbol, { exchangeName, frameName, strategyName });
+}
 /**
  * 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.
@@ -38564,6 +38778,8 @@ const BACKTEST_METHOD_NAME_GET_POSITION_HIGHEST_PROFIT_DISTANCE_PNL_PERCENTAGE =
 const BACKTEST_METHOD_NAME_GET_POSITION_HIGHEST_PROFIT_DISTANCE_PNL_COST = "BacktestUtils.getPositionHighestProfitDistancePnlCost";
 const BACKTEST_METHOD_NAME_GET_POSITION_HIGHEST_MAX_DRAWDOWN_PNL_PERCENTAGE = "BacktestUtils.getPositionHighestMaxDrawdownPnlPercentage";
 const BACKTEST_METHOD_NAME_GET_POSITION_HIGHEST_MAX_DRAWDOWN_PNL_COST = "BacktestUtils.getPositionHighestMaxDrawdownPnlCost";
+const BACKTEST_METHOD_NAME_GET_MAX_DRAWDOWN_DISTANCE_PNL_PERCENTAGE = "BacktestUtils.getMaxDrawdownDistancePnlPercentage";
+const BACKTEST_METHOD_NAME_GET_MAX_DRAWDOWN_DISTANCE_PNL_COST = "BacktestUtils.getMaxDrawdownDistancePnlCost";
 const BACKTEST_METHOD_NAME_GET_POSITION_ENTRY_OVERLAP = "BacktestUtils.getPositionEntryOverlap";
 const BACKTEST_METHOD_NAME_GET_POSITION_PARTIAL_OVERLAP = "BacktestUtils.getPositionPartialOverlap";
 const BACKTEST_METHOD_NAME_BREAKEVEN = "Backtest.commitBreakeven";
@@ -39945,6 +40161,62 @@ class BacktestUtils {
             }
             return await backtest.strategyCoreService.getPositionHighestMaxDrawdownPnlCost(true, symbol, context);
         };
+        /**
+         * 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
+         */
+        this.getMaxDrawdownDistancePnlPercentage = async (symbol, context) => {
+            backtest.loggerService.info(BACKTEST_METHOD_NAME_GET_MAX_DRAWDOWN_DISTANCE_PNL_PERCENTAGE, {
+                symbol,
+                context,
+            });
+            backtest.strategyValidationService.validate(context.strategyName, BACKTEST_METHOD_NAME_GET_MAX_DRAWDOWN_DISTANCE_PNL_PERCENTAGE);
+            backtest.exchangeValidationService.validate(context.exchangeName, BACKTEST_METHOD_NAME_GET_MAX_DRAWDOWN_DISTANCE_PNL_PERCENTAGE);
+            {
+                const { riskName, riskList, actions } = backtest.strategySchemaService.get(context.strategyName);
+                riskName &&
+                    backtest.riskValidationService.validate(riskName, BACKTEST_METHOD_NAME_GET_MAX_DRAWDOWN_DISTANCE_PNL_PERCENTAGE);
+                riskList &&
+                    riskList.forEach((riskName) => backtest.riskValidationService.validate(riskName, BACKTEST_METHOD_NAME_GET_MAX_DRAWDOWN_DISTANCE_PNL_PERCENTAGE));
+                actions &&
+                    actions.forEach((actionName) => backtest.actionValidationService.validate(actionName, BACKTEST_METHOD_NAME_GET_MAX_DRAWDOWN_DISTANCE_PNL_PERCENTAGE));
+            }
+            return await backtest.strategyCoreService.getMaxDrawdownDistancePnlPercentage(true, symbol, context);
+        };
+        /**
+         * 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
+         */
+        this.getMaxDrawdownDistancePnlCost = async (symbol, context) => {
+            backtest.loggerService.info(BACKTEST_METHOD_NAME_GET_MAX_DRAWDOWN_DISTANCE_PNL_COST, {
+                symbol,
+                context,
+            });
+            backtest.strategyValidationService.validate(context.strategyName, BACKTEST_METHOD_NAME_GET_MAX_DRAWDOWN_DISTANCE_PNL_COST);
+            backtest.exchangeValidationService.validate(context.exchangeName, BACKTEST_METHOD_NAME_GET_MAX_DRAWDOWN_DISTANCE_PNL_COST);
+            {
+                const { riskName, riskList, actions } = backtest.strategySchemaService.get(context.strategyName);
+                riskName &&
+                    backtest.riskValidationService.validate(riskName, BACKTEST_METHOD_NAME_GET_MAX_DRAWDOWN_DISTANCE_PNL_COST);
+                riskList &&
+                    riskList.forEach((riskName) => backtest.riskValidationService.validate(riskName, BACKTEST_METHOD_NAME_GET_MAX_DRAWDOWN_DISTANCE_PNL_COST));
+                actions &&
+                    actions.forEach((actionName) => backtest.actionValidationService.validate(actionName, BACKTEST_METHOD_NAME_GET_MAX_DRAWDOWN_DISTANCE_PNL_COST));
+            }
+            return await backtest.strategyCoreService.getMaxDrawdownDistancePnlCost(true, symbol, context);
+        };
         /**
          * 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.
@@ -40079,7 +40351,7 @@ 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
@@ -40089,14 +40361,14 @@ class BacktestUtils {
          *   exchangeName: "binance",
          *   frameName: "frame1",
          *   strategyName: "my-strategy"
-         * }, "manual-cancel-001");
+         * }, { id: "manual-cancel-001" });
          * ```
          */
-        this.commitCancelScheduled = async (symbol, context, cancelId) => {
+        this.commitCancelScheduled = async (symbol, context, payload = {}) => {
             backtest.loggerService.info(BACKTEST_METHOD_NAME_CANCEL_SCHEDULED, {
                 symbol,
                 context,
-                cancelId,
+                payload,
             });
             backtest.strategyValidationService.validate(context.strategyName, BACKTEST_METHOD_NAME_CANCEL_SCHEDULED);
             backtest.exchangeValidationService.validate(context.exchangeName, BACKTEST_METHOD_NAME_CANCEL_SCHEDULED);
@@ -40109,7 +40381,7 @@ class BacktestUtils {
                 actions &&
                     actions.forEach((actionName) => backtest.actionValidationService.validate(actionName, BACKTEST_METHOD_NAME_CANCEL_SCHEDULED));
             }
-            await backtest.strategyCoreService.cancelScheduled(true, symbol, context, cancelId);
+            await backtest.strategyCoreService.cancelScheduled(true, symbol, context, payload);
         };
         /**
          * Closes the pending signal without stopping the strategy.
@@ -40120,7 +40392,7 @@ 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
@@ -40130,14 +40402,14 @@ class BacktestUtils {
          *   exchangeName: "binance",
          *   strategyName: "my-strategy",
          *   frameName: "1m"
-         * }, "manual-close-001");
+         * }, { id: "manual-close-001" });
          * ```
          */
-        this.commitClosePending = async (symbol, context, closeId) => {
+        this.commitClosePending = async (symbol, context, payload = {}) => {
             backtest.loggerService.info(BACKTEST_METHOD_NAME_CLOSE_PENDING, {
                 symbol,
                 context,
-                closeId,
+                payload,
             });
             backtest.strategyValidationService.validate(context.strategyName, BACKTEST_METHOD_NAME_CLOSE_PENDING);
             backtest.exchangeValidationService.validate(context.exchangeName, BACKTEST_METHOD_NAME_CLOSE_PENDING);
@@ -40150,7 +40422,7 @@ class BacktestUtils {
                 actions &&
                     actions.forEach((actionName) => backtest.actionValidationService.validate(actionName, BACKTEST_METHOD_NAME_CLOSE_PENDING));
             }
-            await backtest.strategyCoreService.closePending(true, symbol, context, closeId);
+            await backtest.strategyCoreService.closePending(true, symbol, context, payload);
         };
         /**
          * Executes partial close at profit level (moving toward TP).
@@ -40786,7 +41058,7 @@ 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
@@ -40796,14 +41068,14 @@ class BacktestUtils {
          *   strategyName: "my-strategy",
          *   exchangeName: "binance",
          *   frameName: "1h"
-         * }, "manual-activate-001");
+         * }, { id: "manual-activate-001" });
          * ```
          */
-        this.commitActivateScheduled = async (symbol, context, activateId) => {
+        this.commitActivateScheduled = async (symbol, context, payload = {}) => {
             backtest.loggerService.info(BACKTEST_METHOD_NAME_ACTIVATE_SCHEDULED, {
                 symbol,
                 context,
-                activateId,
+                payload,
             });
             backtest.strategyValidationService.validate(context.strategyName, BACKTEST_METHOD_NAME_ACTIVATE_SCHEDULED);
             backtest.exchangeValidationService.validate(context.exchangeName, BACKTEST_METHOD_NAME_ACTIVATE_SCHEDULED);
@@ -40816,7 +41088,7 @@ class BacktestUtils {
                 actions &&
                     actions.forEach((actionName) => backtest.actionValidationService.validate(actionName, BACKTEST_METHOD_NAME_ACTIVATE_SCHEDULED));
             }
-            await backtest.strategyCoreService.activateScheduled(true, symbol, context, activateId);
+            await backtest.strategyCoreService.activateScheduled(true, symbol, context, payload);
         };
         /**
          * Adds a new DCA entry to the active pending signal.
@@ -41074,6 +41346,8 @@ const LIVE_METHOD_NAME_GET_POSITION_HIGHEST_PROFIT_DISTANCE_PNL_PERCENTAGE = "Li
 const LIVE_METHOD_NAME_GET_POSITION_HIGHEST_PROFIT_DISTANCE_PNL_COST = "LiveUtils.getPositionHighestProfitDistancePnlCost";
 const LIVE_METHOD_NAME_GET_POSITION_HIGHEST_MAX_DRAWDOWN_PNL_PERCENTAGE = "LiveUtils.getPositionHighestMaxDrawdownPnlPercentage";
 const LIVE_METHOD_NAME_GET_POSITION_HIGHEST_MAX_DRAWDOWN_PNL_COST = "LiveUtils.getPositionHighestMaxDrawdownPnlCost";
+const LIVE_METHOD_NAME_GET_MAX_DRAWDOWN_DISTANCE_PNL_PERCENTAGE = "LiveUtils.getMaxDrawdownDistancePnlPercentage";
+const LIVE_METHOD_NAME_GET_MAX_DRAWDOWN_DISTANCE_PNL_COST = "LiveUtils.getMaxDrawdownDistancePnlCost";
 const LIVE_METHOD_NAME_GET_POSITION_ENTRY_OVERLAP = "LiveUtils.getPositionEntryOverlap";
 const LIVE_METHOD_NAME_GET_POSITION_PARTIAL_OVERLAP = "LiveUtils.getPositionPartialOverlap";
 const LIVE_METHOD_NAME_BREAKEVEN = "Live.commitBreakeven";
@@ -42598,6 +42872,70 @@ class LiveUtils {
                 frameName: "",
             });
         };
+        /**
+         * 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
+         */
+        this.getMaxDrawdownDistancePnlPercentage = async (symbol, context) => {
+            backtest.loggerService.info(LIVE_METHOD_NAME_GET_MAX_DRAWDOWN_DISTANCE_PNL_PERCENTAGE, {
+                symbol,
+                context,
+            });
+            backtest.strategyValidationService.validate(context.strategyName, LIVE_METHOD_NAME_GET_MAX_DRAWDOWN_DISTANCE_PNL_PERCENTAGE);
+            backtest.exchangeValidationService.validate(context.exchangeName, LIVE_METHOD_NAME_GET_MAX_DRAWDOWN_DISTANCE_PNL_PERCENTAGE);
+            {
+                const { riskName, riskList, actions } = backtest.strategySchemaService.get(context.strategyName);
+                riskName &&
+                    backtest.riskValidationService.validate(riskName, LIVE_METHOD_NAME_GET_MAX_DRAWDOWN_DISTANCE_PNL_PERCENTAGE);
+                riskList &&
+                    riskList.forEach((riskName) => backtest.riskValidationService.validate(riskName, LIVE_METHOD_NAME_GET_MAX_DRAWDOWN_DISTANCE_PNL_PERCENTAGE));
+                actions &&
+                    actions.forEach((actionName) => backtest.actionValidationService.validate(actionName, LIVE_METHOD_NAME_GET_MAX_DRAWDOWN_DISTANCE_PNL_PERCENTAGE));
+            }
+            return await backtest.strategyCoreService.getMaxDrawdownDistancePnlPercentage(false, symbol, {
+                strategyName: context.strategyName,
+                exchangeName: context.exchangeName,
+                frameName: "",
+            });
+        };
+        /**
+         * 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
+         */
+        this.getMaxDrawdownDistancePnlCost = async (symbol, context) => {
+            backtest.loggerService.info(LIVE_METHOD_NAME_GET_MAX_DRAWDOWN_DISTANCE_PNL_COST, {
+                symbol,
+                context,
+            });
+            backtest.strategyValidationService.validate(context.strategyName, LIVE_METHOD_NAME_GET_MAX_DRAWDOWN_DISTANCE_PNL_COST);
+            backtest.exchangeValidationService.validate(context.exchangeName, LIVE_METHOD_NAME_GET_MAX_DRAWDOWN_DISTANCE_PNL_COST);
+            {
+                const { riskName, riskList, actions } = backtest.strategySchemaService.get(context.strategyName);
+                riskName &&
+                    backtest.riskValidationService.validate(riskName, LIVE_METHOD_NAME_GET_MAX_DRAWDOWN_DISTANCE_PNL_COST);
+                riskList &&
+                    riskList.forEach((riskName) => backtest.riskValidationService.validate(riskName, LIVE_METHOD_NAME_GET_MAX_DRAWDOWN_DISTANCE_PNL_COST));
+                actions &&
+                    actions.forEach((actionName) => backtest.actionValidationService.validate(actionName, LIVE_METHOD_NAME_GET_MAX_DRAWDOWN_DISTANCE_PNL_COST));
+            }
+            return await backtest.strategyCoreService.getMaxDrawdownDistancePnlCost(false, symbol, {
+                strategyName: context.strategyName,
+                exchangeName: context.exchangeName,
+                frameName: "",
+            });
+        };
         /**
          * 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.
@@ -42739,7 +43077,7 @@ 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
@@ -42749,14 +43087,14 @@ class LiveUtils {
          *   exchangeName: "binance",
          *   frameName: "",
          *   strategyName: "my-strategy"
-         * }, "manual-cancel-001");
+         * }, { id: "manual-cancel-001" });
          * ```
          */
-        this.commitCancelScheduled = async (symbol, context, cancelId) => {
+        this.commitCancelScheduled = async (symbol, context, payload = {}) => {
             backtest.loggerService.info(LIVE_METHOD_NAME_CANCEL_SCHEDULED, {
                 symbol,
                 context,
-                cancelId,
+                payload,
             });
             backtest.strategyValidationService.validate(context.strategyName, LIVE_METHOD_NAME_CANCEL_SCHEDULED);
             backtest.exchangeValidationService.validate(context.exchangeName, LIVE_METHOD_NAME_CANCEL_SCHEDULED);
@@ -42773,7 +43111,7 @@ class LiveUtils {
                 strategyName: context.strategyName,
                 exchangeName: context.exchangeName,
                 frameName: "",
-            }, cancelId);
+            }, payload);
         };
         /**
          * Closes the pending signal without stopping the strategy.
@@ -42784,7 +43122,7 @@ 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
@@ -42793,14 +43131,14 @@ class LiveUtils {
          * await Live.commitClose("BTCUSDT", {
          *   exchangeName: "binance",
          *   strategyName: "my-strategy"
-         * }, "manual-close-001");
+         * }, { id: "manual-close-001" });
          * ```
          */
-        this.commitClosePending = async (symbol, context, closeId) => {
+        this.commitClosePending = async (symbol, context, payload = {}) => {
             backtest.loggerService.info(LIVE_METHOD_NAME_CLOSE_PENDING, {
                 symbol,
                 context,
-                closeId,
+                payload,
             });
             backtest.strategyValidationService.validate(context.strategyName, LIVE_METHOD_NAME_CLOSE_PENDING);
             backtest.exchangeValidationService.validate(context.exchangeName, LIVE_METHOD_NAME_CLOSE_PENDING);
@@ -42817,7 +43155,7 @@ class LiveUtils {
                 strategyName: context.strategyName,
                 exchangeName: context.exchangeName,
                 frameName: "",
-            }, closeId);
+            }, payload);
         };
         /**
          * Executes partial close at profit level (moving toward TP).
@@ -43611,7 +43949,7 @@ 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
@@ -43620,14 +43958,14 @@ class LiveUtils {
          * await Live.commitActivateScheduled("BTCUSDT", {
          *   strategyName: "my-strategy",
          *   exchangeName: "binance"
-         * }, "manual-activate-001");
+         * }, { id: "manual-activate-001" });
          * ```
          */
-        this.commitActivateScheduled = async (symbol, context, activateId) => {
+        this.commitActivateScheduled = async (symbol, context, payload = {}) => {
             backtest.loggerService.info(LIVE_METHOD_NAME_ACTIVATE_SCHEDULED, {
                 symbol,
                 context,
-                activateId,
+                payload,
             });
             backtest.strategyValidationService.validate(context.strategyName, LIVE_METHOD_NAME_ACTIVATE_SCHEDULED);
             backtest.exchangeValidationService.validate(context.exchangeName, LIVE_METHOD_NAME_ACTIVATE_SCHEDULED);
@@ -43644,7 +43982,7 @@ class LiveUtils {
                 strategyName: context.strategyName,
                 exchangeName: context.exchangeName,
                 frameName: "",
-            }, activateId);
+            }, payload);
         };
         /**
          * Adds a new DCA entry to the active pending signal.
@@ -49715,6 +50053,741 @@ class MaxDrawdownUtils {
  */
 const MaxDrawdown = new MaxDrawdownUtils();
 
+const REFLECT_METHOD_NAME_GET_POSITION_PNL_PERCENT = "ReflectUtils.getPositionPnlPercent";
+const REFLECT_METHOD_NAME_GET_POSITION_PNL_COST = "ReflectUtils.getPositionPnlCost";
+const REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_PROFIT_PRICE = "ReflectUtils.getPositionHighestProfitPrice";
+const REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_PROFIT_TIMESTAMP = "ReflectUtils.getPositionHighestProfitTimestamp";
+const REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_PNL_PERCENTAGE = "ReflectUtils.getPositionHighestPnlPercentage";
+const REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_PNL_COST = "ReflectUtils.getPositionHighestPnlCost";
+const REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_PROFIT_BREAKEVEN = "ReflectUtils.getPositionHighestProfitBreakeven";
+const REFLECT_METHOD_NAME_GET_POSITION_DRAWDOWN_MINUTES = "ReflectUtils.getPositionDrawdownMinutes";
+const REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_PROFIT_MINUTES = "ReflectUtils.getPositionHighestProfitMinutes";
+const REFLECT_METHOD_NAME_GET_POSITION_MAX_DRAWDOWN_MINUTES = "ReflectUtils.getPositionMaxDrawdownMinutes";
+const REFLECT_METHOD_NAME_GET_POSITION_MAX_DRAWDOWN_PRICE = "ReflectUtils.getPositionMaxDrawdownPrice";
+const REFLECT_METHOD_NAME_GET_POSITION_MAX_DRAWDOWN_TIMESTAMP = "ReflectUtils.getPositionMaxDrawdownTimestamp";
+const REFLECT_METHOD_NAME_GET_POSITION_MAX_DRAWDOWN_PNL_PERCENTAGE = "ReflectUtils.getPositionMaxDrawdownPnlPercentage";
+const REFLECT_METHOD_NAME_GET_POSITION_MAX_DRAWDOWN_PNL_COST = "ReflectUtils.getPositionMaxDrawdownPnlCost";
+const REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_PROFIT_DISTANCE_PNL_PERCENTAGE = "ReflectUtils.getPositionHighestProfitDistancePnlPercentage";
+const REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_PROFIT_DISTANCE_PNL_COST = "ReflectUtils.getPositionHighestProfitDistancePnlCost";
+const REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_MAX_DRAWDOWN_PNL_PERCENTAGE = "ReflectUtils.getPositionHighestMaxDrawdownPnlPercentage";
+const REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_MAX_DRAWDOWN_PNL_COST = "ReflectUtils.getPositionHighestMaxDrawdownPnlCost";
+const REFLECT_METHOD_NAME_GET_MAX_DRAWDOWN_DISTANCE_PNL_PERCENTAGE = "ReflectUtils.getMaxDrawdownDistancePnlPercentage";
+const REFLECT_METHOD_NAME_GET_MAX_DRAWDOWN_DISTANCE_PNL_COST = "ReflectUtils.getMaxDrawdownDistancePnlCost";
+/**
+ * Utility class for real-time position reflection: PNL, peak profit, and drawdown queries.
+ *
+ * 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
+ * ```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}%`);
+ * ```
+ */
+class ReflectUtils {
+    constructor() {
+        /**
+         * 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}%`);
+         * ```
+         */
+        this.getPositionPnlPercent = async (symbol, currentPrice, context, backtest$1 = false) => {
+            backtest.loggerService.info(REFLECT_METHOD_NAME_GET_POSITION_PNL_PERCENT, { symbol, currentPrice, context });
+            backtest.strategyValidationService.validate(context.strategyName, REFLECT_METHOD_NAME_GET_POSITION_PNL_PERCENT);
+            backtest.exchangeValidationService.validate(context.exchangeName, REFLECT_METHOD_NAME_GET_POSITION_PNL_PERCENT);
+            context.frameName && backtest.frameValidationService.validate(context.frameName, REFLECT_METHOD_NAME_GET_POSITION_PNL_PERCENT);
+            {
+                const { riskName, riskList, actions } = backtest.strategySchemaService.get(context.strategyName);
+                riskName && backtest.riskValidationService.validate(riskName, REFLECT_METHOD_NAME_GET_POSITION_PNL_PERCENT);
+                riskList && riskList.forEach((riskName) => backtest.riskValidationService.validate(riskName, REFLECT_METHOD_NAME_GET_POSITION_PNL_PERCENT));
+                actions && actions.forEach((actionName) => backtest.actionValidationService.validate(actionName, REFLECT_METHOD_NAME_GET_POSITION_PNL_PERCENT));
+            }
+            return await backtest.strategyCoreService.getPositionPnlPercent(backtest$1, symbol, currentPrice, context);
+        };
+        /**
+         * 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}`);
+         * ```
+         */
+        this.getPositionPnlCost = async (symbol, currentPrice, context, backtest$1 = false) => {
+            backtest.loggerService.info(REFLECT_METHOD_NAME_GET_POSITION_PNL_COST, { symbol, currentPrice, context });
+            backtest.strategyValidationService.validate(context.strategyName, REFLECT_METHOD_NAME_GET_POSITION_PNL_COST);
+            backtest.exchangeValidationService.validate(context.exchangeName, REFLECT_METHOD_NAME_GET_POSITION_PNL_COST);
+            context.frameName && backtest.frameValidationService.validate(context.frameName, REFLECT_METHOD_NAME_GET_POSITION_PNL_COST);
+            {
+                const { riskName, riskList, actions } = backtest.strategySchemaService.get(context.strategyName);
+                riskName && backtest.riskValidationService.validate(riskName, REFLECT_METHOD_NAME_GET_POSITION_PNL_COST);
+                riskList && riskList.forEach((riskName) => backtest.riskValidationService.validate(riskName, REFLECT_METHOD_NAME_GET_POSITION_PNL_COST));
+                actions && actions.forEach((actionName) => backtest.actionValidationService.validate(actionName, REFLECT_METHOD_NAME_GET_POSITION_PNL_COST));
+            }
+            return await backtest.strategyCoreService.getPositionPnlCost(backtest$1, symbol, currentPrice, context);
+        };
+        /**
+         * 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}`);
+         * ```
+         */
+        this.getPositionHighestProfitPrice = async (symbol, context, backtest$1 = false) => {
+            backtest.loggerService.info(REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_PROFIT_PRICE, { symbol, context });
+            backtest.strategyValidationService.validate(context.strategyName, REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_PROFIT_PRICE);
+            backtest.exchangeValidationService.validate(context.exchangeName, REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_PROFIT_PRICE);
+            context.frameName && backtest.frameValidationService.validate(context.frameName, REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_PROFIT_PRICE);
+            {
+                const { riskName, riskList, actions } = backtest.strategySchemaService.get(context.strategyName);
+                riskName && backtest.riskValidationService.validate(riskName, REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_PROFIT_PRICE);
+                riskList && riskList.forEach((riskName) => backtest.riskValidationService.validate(riskName, REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_PROFIT_PRICE));
+                actions && actions.forEach((actionName) => backtest.actionValidationService.validate(actionName, REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_PROFIT_PRICE));
+            }
+            return await backtest.strategyCoreService.getPositionHighestProfitPrice(backtest$1, symbol, context);
+        };
+        /**
+         * 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()}`);
+         * ```
+         */
+        this.getPositionHighestProfitTimestamp = async (symbol, context, backtest$1 = false) => {
+            backtest.loggerService.info(REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_PROFIT_TIMESTAMP, { symbol, context });
+            backtest.strategyValidationService.validate(context.strategyName, REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_PROFIT_TIMESTAMP);
+            backtest.exchangeValidationService.validate(context.exchangeName, REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_PROFIT_TIMESTAMP);
+            context.frameName && backtest.frameValidationService.validate(context.frameName, REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_PROFIT_TIMESTAMP);
+            {
+                const { riskName, riskList, actions } = backtest.strategySchemaService.get(context.strategyName);
+                riskName && backtest.riskValidationService.validate(riskName, REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_PROFIT_TIMESTAMP);
+                riskList && riskList.forEach((riskName) => backtest.riskValidationService.validate(riskName, REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_PROFIT_TIMESTAMP));
+                actions && actions.forEach((actionName) => backtest.actionValidationService.validate(actionName, REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_PROFIT_TIMESTAMP));
+            }
+            return await backtest.strategyCoreService.getPositionHighestProfitTimestamp(backtest$1, symbol, context);
+        };
+        /**
+         * 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}%`);
+         * ```
+         */
+        this.getPositionHighestPnlPercentage = async (symbol, context, backtest$1 = false) => {
+            backtest.loggerService.info(REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_PNL_PERCENTAGE, { symbol, context });
+            backtest.strategyValidationService.validate(context.strategyName, REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_PNL_PERCENTAGE);
+            backtest.exchangeValidationService.validate(context.exchangeName, REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_PNL_PERCENTAGE);
+            context.frameName && backtest.frameValidationService.validate(context.frameName, REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_PNL_PERCENTAGE);
+            {
+                const { riskName, riskList, actions } = backtest.strategySchemaService.get(context.strategyName);
+                riskName && backtest.riskValidationService.validate(riskName, REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_PNL_PERCENTAGE);
+                riskList && riskList.forEach((riskName) => backtest.riskValidationService.validate(riskName, REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_PNL_PERCENTAGE));
+                actions && actions.forEach((actionName) => backtest.actionValidationService.validate(actionName, REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_PNL_PERCENTAGE));
+            }
+            return await backtest.strategyCoreService.getPositionHighestPnlPercentage(backtest$1, symbol, context);
+        };
+        /**
+         * 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}`);
+         * ```
+         */
+        this.getPositionHighestPnlCost = async (symbol, context, backtest$1 = false) => {
+            backtest.loggerService.info(REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_PNL_COST, { symbol, context });
+            backtest.strategyValidationService.validate(context.strategyName, REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_PNL_COST);
+            backtest.exchangeValidationService.validate(context.exchangeName, REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_PNL_COST);
+            context.frameName && backtest.frameValidationService.validate(context.frameName, REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_PNL_COST);
+            {
+                const { riskName, riskList, actions } = backtest.strategySchemaService.get(context.strategyName);
+                riskName && backtest.riskValidationService.validate(riskName, REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_PNL_COST);
+                riskList && riskList.forEach((riskName) => backtest.riskValidationService.validate(riskName, REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_PNL_COST));
+                actions && actions.forEach((actionName) => backtest.actionValidationService.validate(actionName, REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_PNL_COST));
+            }
+            return await backtest.strategyCoreService.getPositionHighestPnlCost(backtest$1, symbol, context);
+        };
+        /**
+         * 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}`);
+         * ```
+         */
+        this.getPositionHighestProfitBreakeven = async (symbol, context, backtest$1 = false) => {
+            backtest.loggerService.info(REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_PROFIT_BREAKEVEN, { symbol, context });
+            backtest.strategyValidationService.validate(context.strategyName, REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_PROFIT_BREAKEVEN);
+            backtest.exchangeValidationService.validate(context.exchangeName, REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_PROFIT_BREAKEVEN);
+            context.frameName && backtest.frameValidationService.validate(context.frameName, REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_PROFIT_BREAKEVEN);
+            {
+                const { riskName, riskList, actions } = backtest.strategySchemaService.get(context.strategyName);
+                riskName && backtest.riskValidationService.validate(riskName, REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_PROFIT_BREAKEVEN);
+                riskList && riskList.forEach((riskName) => backtest.riskValidationService.validate(riskName, REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_PROFIT_BREAKEVEN));
+                actions && actions.forEach((actionName) => backtest.actionValidationService.validate(actionName, REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_PROFIT_BREAKEVEN));
+            }
+            return await backtest.strategyCoreService.getPositionHighestProfitBreakeven(backtest$1, symbol, context);
+        };
+        /**
+         * 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`);
+         * ```
+         */
+        this.getPositionDrawdownMinutes = async (symbol, context, backtest$1 = false) => {
+            backtest.loggerService.info(REFLECT_METHOD_NAME_GET_POSITION_DRAWDOWN_MINUTES, { symbol, context });
+            backtest.strategyValidationService.validate(context.strategyName, REFLECT_METHOD_NAME_GET_POSITION_DRAWDOWN_MINUTES);
+            backtest.exchangeValidationService.validate(context.exchangeName, REFLECT_METHOD_NAME_GET_POSITION_DRAWDOWN_MINUTES);
+            context.frameName && backtest.frameValidationService.validate(context.frameName, REFLECT_METHOD_NAME_GET_POSITION_DRAWDOWN_MINUTES);
+            {
+                const { riskName, riskList, actions } = backtest.strategySchemaService.get(context.strategyName);
+                riskName && backtest.riskValidationService.validate(riskName, REFLECT_METHOD_NAME_GET_POSITION_DRAWDOWN_MINUTES);
+                riskList && riskList.forEach((riskName) => backtest.riskValidationService.validate(riskName, REFLECT_METHOD_NAME_GET_POSITION_DRAWDOWN_MINUTES));
+                actions && actions.forEach((actionName) => backtest.actionValidationService.validate(actionName, REFLECT_METHOD_NAME_GET_POSITION_DRAWDOWN_MINUTES));
+            }
+            return await backtest.strategyCoreService.getPositionDrawdownMinutes(backtest$1, symbol, context);
+        };
+        /**
+         * 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`);
+         * ```
+         */
+        this.getPositionHighestProfitMinutes = async (symbol, context, backtest$1 = false) => {
+            backtest.loggerService.info(REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_PROFIT_MINUTES, { symbol, context });
+            backtest.strategyValidationService.validate(context.strategyName, REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_PROFIT_MINUTES);
+            backtest.exchangeValidationService.validate(context.exchangeName, REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_PROFIT_MINUTES);
+            context.frameName && backtest.frameValidationService.validate(context.frameName, REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_PROFIT_MINUTES);
+            {
+                const { riskName, riskList, actions } = backtest.strategySchemaService.get(context.strategyName);
+                riskName && backtest.riskValidationService.validate(riskName, REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_PROFIT_MINUTES);
+                riskList && riskList.forEach((riskName) => backtest.riskValidationService.validate(riskName, REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_PROFIT_MINUTES));
+                actions && actions.forEach((actionName) => backtest.actionValidationService.validate(actionName, REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_PROFIT_MINUTES));
+            }
+            return await backtest.strategyCoreService.getPositionHighestProfitMinutes(backtest$1, symbol, context);
+        };
+        /**
+         * 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`);
+         * ```
+         */
+        this.getPositionMaxDrawdownMinutes = async (symbol, context, backtest$1 = false) => {
+            backtest.loggerService.info(REFLECT_METHOD_NAME_GET_POSITION_MAX_DRAWDOWN_MINUTES, { symbol, context });
+            backtest.strategyValidationService.validate(context.strategyName, REFLECT_METHOD_NAME_GET_POSITION_MAX_DRAWDOWN_MINUTES);
+            backtest.exchangeValidationService.validate(context.exchangeName, REFLECT_METHOD_NAME_GET_POSITION_MAX_DRAWDOWN_MINUTES);
+            context.frameName && backtest.frameValidationService.validate(context.frameName, REFLECT_METHOD_NAME_GET_POSITION_MAX_DRAWDOWN_MINUTES);
+            {
+                const { riskName, riskList, actions } = backtest.strategySchemaService.get(context.strategyName);
+                riskName && backtest.riskValidationService.validate(riskName, REFLECT_METHOD_NAME_GET_POSITION_MAX_DRAWDOWN_MINUTES);
+                riskList && riskList.forEach((riskName) => backtest.riskValidationService.validate(riskName, REFLECT_METHOD_NAME_GET_POSITION_MAX_DRAWDOWN_MINUTES));
+                actions && actions.forEach((actionName) => backtest.actionValidationService.validate(actionName, REFLECT_METHOD_NAME_GET_POSITION_MAX_DRAWDOWN_MINUTES));
+            }
+            return await backtest.strategyCoreService.getPositionMaxDrawdownMinutes(backtest$1, symbol, context);
+        };
+        /**
+         * 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}`);
+         * ```
+         */
+        this.getPositionMaxDrawdownPrice = async (symbol, context, backtest$1 = false) => {
+            backtest.loggerService.info(REFLECT_METHOD_NAME_GET_POSITION_MAX_DRAWDOWN_PRICE, { symbol, context });
+            backtest.strategyValidationService.validate(context.strategyName, REFLECT_METHOD_NAME_GET_POSITION_MAX_DRAWDOWN_PRICE);
+            backtest.exchangeValidationService.validate(context.exchangeName, REFLECT_METHOD_NAME_GET_POSITION_MAX_DRAWDOWN_PRICE);
+            context.frameName && backtest.frameValidationService.validate(context.frameName, REFLECT_METHOD_NAME_GET_POSITION_MAX_DRAWDOWN_PRICE);
+            {
+                const { riskName, riskList, actions } = backtest.strategySchemaService.get(context.strategyName);
+                riskName && backtest.riskValidationService.validate(riskName, REFLECT_METHOD_NAME_GET_POSITION_MAX_DRAWDOWN_PRICE);
+                riskList && riskList.forEach((riskName) => backtest.riskValidationService.validate(riskName, REFLECT_METHOD_NAME_GET_POSITION_MAX_DRAWDOWN_PRICE));
+                actions && actions.forEach((actionName) => backtest.actionValidationService.validate(actionName, REFLECT_METHOD_NAME_GET_POSITION_MAX_DRAWDOWN_PRICE));
+            }
+            return await backtest.strategyCoreService.getPositionMaxDrawdownPrice(backtest$1, symbol, context);
+        };
+        /**
+         * 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()}`);
+         * ```
+         */
+        this.getPositionMaxDrawdownTimestamp = async (symbol, context, backtest$1 = false) => {
+            backtest.loggerService.info(REFLECT_METHOD_NAME_GET_POSITION_MAX_DRAWDOWN_TIMESTAMP, { symbol, context });
+            backtest.strategyValidationService.validate(context.strategyName, REFLECT_METHOD_NAME_GET_POSITION_MAX_DRAWDOWN_TIMESTAMP);
+            backtest.exchangeValidationService.validate(context.exchangeName, REFLECT_METHOD_NAME_GET_POSITION_MAX_DRAWDOWN_TIMESTAMP);
+            context.frameName && backtest.frameValidationService.validate(context.frameName, REFLECT_METHOD_NAME_GET_POSITION_MAX_DRAWDOWN_TIMESTAMP);
+            {
+                const { riskName, riskList, actions } = backtest.strategySchemaService.get(context.strategyName);
+                riskName && backtest.riskValidationService.validate(riskName, REFLECT_METHOD_NAME_GET_POSITION_MAX_DRAWDOWN_TIMESTAMP);
+                riskList && riskList.forEach((riskName) => backtest.riskValidationService.validate(riskName, REFLECT_METHOD_NAME_GET_POSITION_MAX_DRAWDOWN_TIMESTAMP));
+                actions && actions.forEach((actionName) => backtest.actionValidationService.validate(actionName, REFLECT_METHOD_NAME_GET_POSITION_MAX_DRAWDOWN_TIMESTAMP));
+            }
+            return await backtest.strategyCoreService.getPositionMaxDrawdownTimestamp(backtest$1, symbol, context);
+        };
+        /**
+         * 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}%`);
+         * ```
+         */
+        this.getPositionMaxDrawdownPnlPercentage = async (symbol, context, backtest$1 = false) => {
+            backtest.loggerService.info(REFLECT_METHOD_NAME_GET_POSITION_MAX_DRAWDOWN_PNL_PERCENTAGE, { symbol, context });
+            backtest.strategyValidationService.validate(context.strategyName, REFLECT_METHOD_NAME_GET_POSITION_MAX_DRAWDOWN_PNL_PERCENTAGE);
+            backtest.exchangeValidationService.validate(context.exchangeName, REFLECT_METHOD_NAME_GET_POSITION_MAX_DRAWDOWN_PNL_PERCENTAGE);
+            context.frameName && backtest.frameValidationService.validate(context.frameName, REFLECT_METHOD_NAME_GET_POSITION_MAX_DRAWDOWN_PNL_PERCENTAGE);
+            {
+                const { riskName, riskList, actions } = backtest.strategySchemaService.get(context.strategyName);
+                riskName && backtest.riskValidationService.validate(riskName, REFLECT_METHOD_NAME_GET_POSITION_MAX_DRAWDOWN_PNL_PERCENTAGE);
+                riskList && riskList.forEach((riskName) => backtest.riskValidationService.validate(riskName, REFLECT_METHOD_NAME_GET_POSITION_MAX_DRAWDOWN_PNL_PERCENTAGE));
+                actions && actions.forEach((actionName) => backtest.actionValidationService.validate(actionName, REFLECT_METHOD_NAME_GET_POSITION_MAX_DRAWDOWN_PNL_PERCENTAGE));
+            }
+            return await backtest.strategyCoreService.getPositionMaxDrawdownPnlPercentage(backtest$1, symbol, context);
+        };
+        /**
+         * 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}`);
+         * ```
+         */
+        this.getPositionMaxDrawdownPnlCost = async (symbol, context, backtest$1 = false) => {
+            backtest.loggerService.info(REFLECT_METHOD_NAME_GET_POSITION_MAX_DRAWDOWN_PNL_COST, { symbol, context });
+            backtest.strategyValidationService.validate(context.strategyName, REFLECT_METHOD_NAME_GET_POSITION_MAX_DRAWDOWN_PNL_COST);
+            backtest.exchangeValidationService.validate(context.exchangeName, REFLECT_METHOD_NAME_GET_POSITION_MAX_DRAWDOWN_PNL_COST);
+            context.frameName && backtest.frameValidationService.validate(context.frameName, REFLECT_METHOD_NAME_GET_POSITION_MAX_DRAWDOWN_PNL_COST);
+            {
+                const { riskName, riskList, actions } = backtest.strategySchemaService.get(context.strategyName);
+                riskName && backtest.riskValidationService.validate(riskName, REFLECT_METHOD_NAME_GET_POSITION_MAX_DRAWDOWN_PNL_COST);
+                riskList && riskList.forEach((riskName) => backtest.riskValidationService.validate(riskName, REFLECT_METHOD_NAME_GET_POSITION_MAX_DRAWDOWN_PNL_COST));
+                actions && actions.forEach((actionName) => backtest.actionValidationService.validate(actionName, REFLECT_METHOD_NAME_GET_POSITION_MAX_DRAWDOWN_PNL_COST));
+            }
+            return await backtest.strategyCoreService.getPositionMaxDrawdownPnlCost(backtest$1, symbol, context);
+        };
+        /**
+         * 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`);
+         * ```
+         */
+        this.getPositionHighestProfitDistancePnlPercentage = async (symbol, context, backtest$1 = false) => {
+            backtest.loggerService.info(REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_PROFIT_DISTANCE_PNL_PERCENTAGE, { symbol, context });
+            backtest.strategyValidationService.validate(context.strategyName, REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_PROFIT_DISTANCE_PNL_PERCENTAGE);
+            backtest.exchangeValidationService.validate(context.exchangeName, REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_PROFIT_DISTANCE_PNL_PERCENTAGE);
+            context.frameName && backtest.frameValidationService.validate(context.frameName, REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_PROFIT_DISTANCE_PNL_PERCENTAGE);
+            {
+                const { riskName, riskList, actions } = backtest.strategySchemaService.get(context.strategyName);
+                riskName && backtest.riskValidationService.validate(riskName, REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_PROFIT_DISTANCE_PNL_PERCENTAGE);
+                riskList && riskList.forEach((riskName) => backtest.riskValidationService.validate(riskName, REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_PROFIT_DISTANCE_PNL_PERCENTAGE));
+                actions && actions.forEach((actionName) => backtest.actionValidationService.validate(actionName, REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_PROFIT_DISTANCE_PNL_PERCENTAGE));
+            }
+            return await backtest.strategyCoreService.getPositionHighestProfitDistancePnlPercentage(backtest$1, symbol, context);
+        };
+        /**
+         * 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`);
+         * ```
+         */
+        this.getPositionHighestProfitDistancePnlCost = async (symbol, context, backtest$1 = false) => {
+            backtest.loggerService.info(REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_PROFIT_DISTANCE_PNL_COST, { symbol, context });
+            backtest.strategyValidationService.validate(context.strategyName, REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_PROFIT_DISTANCE_PNL_COST);
+            backtest.exchangeValidationService.validate(context.exchangeName, REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_PROFIT_DISTANCE_PNL_COST);
+            context.frameName && backtest.frameValidationService.validate(context.frameName, REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_PROFIT_DISTANCE_PNL_COST);
+            {
+                const { riskName, riskList, actions } = backtest.strategySchemaService.get(context.strategyName);
+                riskName && backtest.riskValidationService.validate(riskName, REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_PROFIT_DISTANCE_PNL_COST);
+                riskList && riskList.forEach((riskName) => backtest.riskValidationService.validate(riskName, REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_PROFIT_DISTANCE_PNL_COST));
+                actions && actions.forEach((actionName) => backtest.actionValidationService.validate(actionName, REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_PROFIT_DISTANCE_PNL_COST));
+            }
+            return await backtest.strategyCoreService.getPositionHighestProfitDistancePnlCost(backtest$1, symbol, context);
+        };
+        /**
+         * 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`);
+         * ```
+         */
+        this.getPositionHighestMaxDrawdownPnlPercentage = async (symbol, context, backtest$1 = false) => {
+            backtest.loggerService.info(REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_MAX_DRAWDOWN_PNL_PERCENTAGE, { symbol, context });
+            backtest.strategyValidationService.validate(context.strategyName, REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_MAX_DRAWDOWN_PNL_PERCENTAGE);
+            backtest.exchangeValidationService.validate(context.exchangeName, REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_MAX_DRAWDOWN_PNL_PERCENTAGE);
+            context.frameName && backtest.frameValidationService.validate(context.frameName, REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_MAX_DRAWDOWN_PNL_PERCENTAGE);
+            {
+                const { riskName, riskList, actions } = backtest.strategySchemaService.get(context.strategyName);
+                riskName && backtest.riskValidationService.validate(riskName, REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_MAX_DRAWDOWN_PNL_PERCENTAGE);
+                riskList && riskList.forEach((riskName) => backtest.riskValidationService.validate(riskName, REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_MAX_DRAWDOWN_PNL_PERCENTAGE));
+                actions && actions.forEach((actionName) => backtest.actionValidationService.validate(actionName, REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_MAX_DRAWDOWN_PNL_PERCENTAGE));
+            }
+            return await backtest.strategyCoreService.getPositionHighestMaxDrawdownPnlPercentage(backtest$1, symbol, context);
+        };
+        /**
+         * 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`);
+         * ```
+         */
+        this.getPositionHighestMaxDrawdownPnlCost = async (symbol, context, backtest$1 = false) => {
+            backtest.loggerService.info(REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_MAX_DRAWDOWN_PNL_COST, { symbol, context });
+            backtest.strategyValidationService.validate(context.strategyName, REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_MAX_DRAWDOWN_PNL_COST);
+            backtest.exchangeValidationService.validate(context.exchangeName, REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_MAX_DRAWDOWN_PNL_COST);
+            context.frameName && backtest.frameValidationService.validate(context.frameName, REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_MAX_DRAWDOWN_PNL_COST);
+            {
+                const { riskName, riskList, actions } = backtest.strategySchemaService.get(context.strategyName);
+                riskName && backtest.riskValidationService.validate(riskName, REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_MAX_DRAWDOWN_PNL_COST);
+                riskList && riskList.forEach((riskName) => backtest.riskValidationService.validate(riskName, REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_MAX_DRAWDOWN_PNL_COST));
+                actions && actions.forEach((actionName) => backtest.actionValidationService.validate(actionName, REFLECT_METHOD_NAME_GET_POSITION_HIGHEST_MAX_DRAWDOWN_PNL_COST));
+            }
+            return await backtest.strategyCoreService.getPositionHighestMaxDrawdownPnlCost(backtest$1, symbol, context);
+        };
+        /**
+         * 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}%`);
+         * ```
+         */
+        this.getMaxDrawdownDistancePnlPercentage = async (symbol, context, backtest$1 = false) => {
+            backtest.loggerService.info(REFLECT_METHOD_NAME_GET_MAX_DRAWDOWN_DISTANCE_PNL_PERCENTAGE, { symbol, context });
+            backtest.strategyValidationService.validate(context.strategyName, REFLECT_METHOD_NAME_GET_MAX_DRAWDOWN_DISTANCE_PNL_PERCENTAGE);
+            backtest.exchangeValidationService.validate(context.exchangeName, REFLECT_METHOD_NAME_GET_MAX_DRAWDOWN_DISTANCE_PNL_PERCENTAGE);
+            context.frameName && backtest.frameValidationService.validate(context.frameName, REFLECT_METHOD_NAME_GET_MAX_DRAWDOWN_DISTANCE_PNL_PERCENTAGE);
+            {
+                const { riskName, riskList, actions } = backtest.strategySchemaService.get(context.strategyName);
+                riskName && backtest.riskValidationService.validate(riskName, REFLECT_METHOD_NAME_GET_MAX_DRAWDOWN_DISTANCE_PNL_PERCENTAGE);
+                riskList && riskList.forEach((riskName) => backtest.riskValidationService.validate(riskName, REFLECT_METHOD_NAME_GET_MAX_DRAWDOWN_DISTANCE_PNL_PERCENTAGE));
+                actions && actions.forEach((actionName) => backtest.actionValidationService.validate(actionName, REFLECT_METHOD_NAME_GET_MAX_DRAWDOWN_DISTANCE_PNL_PERCENTAGE));
+            }
+            return await backtest.strategyCoreService.getMaxDrawdownDistancePnlPercentage(backtest$1, symbol, context);
+        };
+        /**
+         * 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}`);
+         * ```
+         */
+        this.getMaxDrawdownDistancePnlCost = async (symbol, context, backtest$1 = false) => {
+            backtest.loggerService.info(REFLECT_METHOD_NAME_GET_MAX_DRAWDOWN_DISTANCE_PNL_COST, { symbol, context });
+            backtest.strategyValidationService.validate(context.strategyName, REFLECT_METHOD_NAME_GET_MAX_DRAWDOWN_DISTANCE_PNL_COST);
+            backtest.exchangeValidationService.validate(context.exchangeName, REFLECT_METHOD_NAME_GET_MAX_DRAWDOWN_DISTANCE_PNL_COST);
+            context.frameName && backtest.frameValidationService.validate(context.frameName, REFLECT_METHOD_NAME_GET_MAX_DRAWDOWN_DISTANCE_PNL_COST);
+            {
+                const { riskName, riskList, actions } = backtest.strategySchemaService.get(context.strategyName);
+                riskName && backtest.riskValidationService.validate(riskName, REFLECT_METHOD_NAME_GET_MAX_DRAWDOWN_DISTANCE_PNL_COST);
+                riskList && riskList.forEach((riskName) => backtest.riskValidationService.validate(riskName, REFLECT_METHOD_NAME_GET_MAX_DRAWDOWN_DISTANCE_PNL_COST));
+                actions && actions.forEach((actionName) => backtest.actionValidationService.validate(actionName, REFLECT_METHOD_NAME_GET_MAX_DRAWDOWN_DISTANCE_PNL_COST));
+            }
+            return await backtest.strategyCoreService.getMaxDrawdownDistancePnlCost(backtest$1, symbol, context);
+        };
+    }
+}
+/**
+ * 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`);
+ * ```
+ */
+const Reflect$1 = new ReflectUtils();
+
 /**
  * Utility class containing predefined trading constants for take-profit and stop-loss levels.
  *
@@ -51645,6 +52718,7 @@ const CREATE_SIGNAL_NOTIFICATION_FN = (data) => {
             pnlEntries: data.signal.pnl.pnlEntries,
             scheduledAt: data.signal.scheduledAt,
             currentPrice: data.currentPrice,
+            note: data.signal.note,
             createdAt: data.createdAt,
         };
     }
@@ -51674,6 +52748,7 @@ const CREATE_SIGNAL_NOTIFICATION_FN = (data) => {
             duration: durationMin,
             scheduledAt: data.signal.scheduledAt,
             pendingAt: data.signal.pendingAt,
+            note: data.signal.note,
             createdAt: data.createdAt,
         };
     }
@@ -51710,6 +52785,7 @@ const CREATE_PARTIAL_PROFIT_NOTIFICATION_FN = (data) => ({
     pnlPriceClose: data.data.pnl.priceClose,
     pnlCost: data.data.pnl.pnlCost,
     pnlEntries: data.data.pnl.pnlEntries,
+    note: data.data.note,
     scheduledAt: data.data.scheduledAt,
     pendingAt: data.data.pendingAt,
     createdAt: data.timestamp,
@@ -51745,6 +52821,7 @@ const CREATE_PARTIAL_LOSS_NOTIFICATION_FN = (data) => ({
     pnlPriceClose: data.data.pnl.priceClose,
     pnlCost: data.data.pnl.pnlCost,
     pnlEntries: data.data.pnl.pnlEntries,
+    note: data.data.note,
     scheduledAt: data.data.scheduledAt,
     pendingAt: data.data.pendingAt,
     createdAt: data.timestamp,
@@ -51779,6 +52856,7 @@ const CREATE_BREAKEVEN_NOTIFICATION_FN = (data) => ({
     pnlPriceClose: data.data.pnl.priceClose,
     pnlCost: data.data.pnl.pnlCost,
     pnlEntries: data.data.pnl.pnlEntries,
+    note: data.data.note,
     scheduledAt: data.data.scheduledAt,
     pendingAt: data.data.pendingAt,
     createdAt: data.timestamp,
@@ -51820,6 +52898,7 @@ const CREATE_STRATEGY_COMMIT_NOTIFICATION_FN = (data) => {
             pnlEntries: data.pnl.pnlEntries,
             scheduledAt: data.scheduledAt,
             pendingAt: data.pendingAt,
+            note: data.note,
             createdAt: data.timestamp,
         };
     }
@@ -51852,6 +52931,7 @@ const CREATE_STRATEGY_COMMIT_NOTIFICATION_FN = (data) => {
             pnlEntries: data.pnl.pnlEntries,
             scheduledAt: data.scheduledAt,
             pendingAt: data.pendingAt,
+            note: data.note,
             createdAt: data.timestamp,
         };
     }
@@ -51883,6 +52963,7 @@ const CREATE_STRATEGY_COMMIT_NOTIFICATION_FN = (data) => {
             pnlEntries: data.pnl.pnlEntries,
             scheduledAt: data.scheduledAt,
             pendingAt: data.pendingAt,
+            note: data.note,
             createdAt: data.timestamp,
         };
     }
@@ -51915,6 +52996,7 @@ const CREATE_STRATEGY_COMMIT_NOTIFICATION_FN = (data) => {
             pnlEntries: data.pnl.pnlEntries,
             scheduledAt: data.scheduledAt,
             pendingAt: data.pendingAt,
+            note: data.note,
             createdAt: data.timestamp,
         };
     }
@@ -51947,6 +53029,7 @@ const CREATE_STRATEGY_COMMIT_NOTIFICATION_FN = (data) => {
             pnlEntries: data.pnl.pnlEntries,
             scheduledAt: data.scheduledAt,
             pendingAt: data.pendingAt,
+            note: data.note,
             createdAt: data.timestamp,
         };
     }
@@ -51979,6 +53062,7 @@ const CREATE_STRATEGY_COMMIT_NOTIFICATION_FN = (data) => {
             pnlEntries: data.pnl.pnlEntries,
             scheduledAt: data.scheduledAt,
             pendingAt: data.pendingAt,
+            note: data.note,
             createdAt: data.timestamp,
         };
     }
@@ -52012,6 +53096,7 @@ const CREATE_STRATEGY_COMMIT_NOTIFICATION_FN = (data) => {
             pnlEntries: data.pnl.pnlEntries,
             scheduledAt: data.scheduledAt,
             pendingAt: data.pendingAt,
+            note: data.note,
             createdAt: data.timestamp,
         };
     }
@@ -52035,6 +53120,7 @@ const CREATE_STRATEGY_COMMIT_NOTIFICATION_FN = (data) => {
             pnlPriceClose: data.pnl.priceClose,
             pnlCost: data.pnl.pnlCost,
             pnlEntries: data.pnl.pnlEntries,
+            note: data.note,
             createdAt: data.timestamp,
         };
     }
@@ -52058,6 +53144,7 @@ const CREATE_STRATEGY_COMMIT_NOTIFICATION_FN = (data) => {
             pnlPriceClose: data.pnl.priceClose,
             pnlCost: data.pnl.pnlCost,
             pnlEntries: data.pnl.pnlEntries,
+            note: data.note,
             createdAt: data.timestamp,
         };
     }
@@ -52099,6 +53186,7 @@ const CREATE_SIGNAL_SYNC_NOTIFICATION_FN = (data) => {
             totalPartials: data.totalPartials,
             scheduledAt: data.scheduledAt,
             pendingAt: data.pendingAt,
+            note: data.signal.note,
             createdAt: data.timestamp,
         };
     }
@@ -52131,6 +53219,7 @@ const CREATE_SIGNAL_SYNC_NOTIFICATION_FN = (data) => {
             scheduledAt: data.scheduledAt,
             pendingAt: data.pendingAt,
             closeReason: data.closeReason,
+            note: data.signal.note,
             createdAt: data.timestamp,
         };
     }
@@ -53630,6 +54719,7 @@ const CACHE_METHOD_NAME_FILE = "CacheUtils.file";
 const CACHE_METHOD_NAME_FILE_CLEAR = "CacheUtils.file.clear";
 const CACHE_METHOD_NAME_DISPOSE = "CacheUtils.dispose";
 const CACHE_METHOD_NAME_CLEAR = "CacheUtils.clear";
+const CACHE_METHOD_NAME_RESET_COUNTER = "CacheUtils.resetCounter";
 const CACHE_FILE_INSTANCE_METHOD_NAME_RUN = "CacheFileInstance.run";
 const MS_PER_MINUTE$1 = 60000;
 const INTERVAL_MINUTES$1 = {
@@ -53881,7 +54971,7 @@ class CacheFileInstance {
     /**
      * Clears the index counter.
      */
-    static clearCounter() {
+    static resetCounter() {
         CacheFileInstance._indexCounter = 0;
     }
     /**
@@ -54136,11 +55226,17 @@ class CacheUtils {
          */
         this.clear = () => {
             backtest.loggerService.info(CACHE_METHOD_NAME_CLEAR);
-            {
-                this._getFnInstance.clear();
-                this._getFileInstance.clear();
-            }
-            CacheFileInstance.clearCounter();
+            this._getFnInstance.clear();
+            this._getFileInstance.clear();
+        };
+        /**
+         * 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.
+         */
+        this.resetCounter = () => {
+            backtest.loggerService.info(CACHE_METHOD_NAME_RESET_COUNTER);
+            CacheFileInstance.resetCounter();
         };
     }
 }
@@ -54164,10 +55260,12 @@ const INTERVAL_METHOD_NAME_RUN = "IntervalFnInstance.run";
 const INTERVAL_FILE_INSTANCE_METHOD_NAME_RUN = "IntervalFileInstance.run";
 const INTERVAL_METHOD_NAME_FN = "IntervalUtils.fn";
 const INTERVAL_METHOD_NAME_FN_CLEAR = "IntervalUtils.fn.clear";
+const INTERVAL_METHOD_NAME_FN_GC = "IntervalUtils.fn.gc";
 const INTERVAL_METHOD_NAME_FILE = "IntervalUtils.file";
 const INTERVAL_METHOD_NAME_FILE_CLEAR = "IntervalUtils.file.clear";
 const INTERVAL_METHOD_NAME_DISPOSE = "IntervalUtils.dispose";
 const INTERVAL_METHOD_NAME_CLEAR = "IntervalUtils.clear";
+const INTERVAL_METHOD_NAME_RESET_COUNTER = "IntervalUtils.resetCounter";
 const MS_PER_MINUTE = 60000;
 const INTERVAL_MINUTES = {
     "1m": 1,
@@ -54234,6 +55332,8 @@ const CREATE_KEY_FN = (strategyName, exchangeName, frameName, isBacktest) => {
  *
  * State is kept in memory; use `IntervalFileInstance` for persistence across restarts.
  *
+ * @template F - Concrete function type
+ *
  * @example
  * ```typescript
  * const instance = new IntervalFnInstance(mySignalFn, "1h");
@@ -54249,30 +55349,34 @@ class IntervalFnInstance {
      *
      * @param fn - Function to fire once per interval
      * @param interval - Candle interval that controls the firing boundary
+     * @param key - Optional key generator for argument-based state separation.
+     *              Default: `([symbol]) => symbol`
      */
-    constructor(fn, interval) {
+    constructor(fn, interval, key = ([symbol]) => symbol) {
         this.fn = fn;
         this.interval = interval;
-        /** Stores the last aligned timestamp per context+symbol key. */
+        this.key = key;
+        /** Stores the last aligned timestamp per context+symbol+args key. */
         this._stateMap = new Map();
         /**
          * Execute the signal function with once-per-interval enforcement.
          *
          * Algorithm:
          * 1. Align the current execution context `when` to the interval boundary.
-         * 2. If the stored aligned timestamp for this context+symbol equals the current one → return `null`.
-         * 3. Otherwise call `fn`. If it returns a non-null signal, record the aligned timestamp and return
+         * 2. Build state key from context + key generator result.
+         * 3. If the stored aligned timestamp for this key equals the current one → return `null`.
+         * 4. Otherwise call `fn`. If it returns a non-null signal, record the aligned timestamp and return
          *    the signal. If it returns `null`, leave state unchanged so the next call retries.
          *
          * Requires active method context and execution context.
          *
-         * @param symbol - Trading pair symbol (e.g. "BTCUSDT")
+         * @param args - Arguments forwarded to the wrapped function
          * @returns The value returned by `fn` on the first non-null fire, `null` on all subsequent calls
          *   within the same interval or when `fn` itself returned `null`
          * @throws Error if method context, execution context, or interval is missing
          */
-        this.run = async (symbol) => {
-            backtest.loggerService.debug(INTERVAL_METHOD_NAME_RUN, { symbol });
+        this.run = async (...args) => {
+            backtest.loggerService.debug(INTERVAL_METHOD_NAME_RUN, { args });
             const step = INTERVAL_MINUTES[this.interval];
             {
                 if (!MethodContextService.hasContext()) {
@@ -54286,15 +55390,16 @@ class IntervalFnInstance {
                 }
             }
             const contextKey = CREATE_KEY_FN(backtest.methodContextService.context.strategyName, backtest.methodContextService.context.exchangeName, backtest.methodContextService.context.frameName, backtest.executionContextService.context.backtest);
-            const key = `${contextKey}:${symbol}`;
             const currentWhen = backtest.executionContextService.context.when;
             const currentAligned = align(currentWhen.getTime(), this.interval);
-            if (this._stateMap.get(key) === currentAligned) {
+            const argKey = this.key(args);
+            const stateKey = `${contextKey}:${argKey}`;
+            if (this._stateMap.get(stateKey) === currentAligned) {
                 return null;
             }
-            const result = await this.fn(symbol, currentWhen);
+            const result = await this.fn.apply(null, args);
             if (result !== null) {
-                this._stateMap.set(key, currentAligned);
+                this._stateMap.set(stateKey, currentAligned);
             }
             return result;
         };
@@ -54315,6 +55420,28 @@ class IntervalFnInstance {
                 }
             }
         };
+        /**
+         * Garbage collect expired state entries.
+         *
+         * Removes all entries whose aligned timestamp differs from the current interval boundary.
+         * Call this periodically to free memory from stale state entries.
+         *
+         * Requires active execution context to get current time.
+         *
+         * @returns Number of entries removed
+         */
+        this.gc = () => {
+            const currentWhen = backtest.executionContextService.context.when;
+            const currentAligned = align(currentWhen.getTime(), this.interval);
+            let removed = 0;
+            for (const [key, storedAligned] of this._stateMap.entries()) {
+                if (storedAligned !== currentAligned) {
+                    this._stateMap.delete(key);
+                    removed++;
+                }
+            }
+            return removed;
+        };
     }
 }
 /**
@@ -54328,7 +55455,7 @@ class IntervalFnInstance {
  *
  * Fired state survives process restarts — unlike `IntervalFnInstance` which is in-memory only.
  *
- * @template T - Async function type: `(symbol: string, ...args) => Promise<R | null>`
+ * @template F - Concrete async function type
  *
  * @example
  * ```typescript
@@ -54349,7 +55476,7 @@ class IntervalFileInstance {
      * Resets the index counter to zero.
      * Call this when clearing all instances (e.g. on `IntervalUtils.clear()`).
      */
-    static clearCounter() {
+    static resetCounter() {
         IntervalFileInstance._indexCounter = 0;
     }
     /**
@@ -54358,18 +55485,21 @@ class IntervalFileInstance {
      * @param fn - Async signal function to fire once per interval
      * @param interval - Candle interval that controls the firing boundary
      * @param name - Human-readable bucket name used as the directory prefix
+     * @param key - Dynamic key generator; receives `[symbol, alignMs, ...rest]`.
+     *              Default: `([symbol, alignMs]) => \`${symbol}_${alignMs}\``
      */
-    constructor(fn, interval, name) {
+    constructor(fn, interval, name, key = ([symbol, alignMs]) => `${symbol}_${alignMs}`) {
         this.fn = fn;
         this.interval = interval;
         this.name = name;
+        this.key = key;
         /**
          * Execute the async function with persistent once-per-interval enforcement.
          *
          * Algorithm:
          * 1. Build bucket = `${name}_${interval}_${index}` — fixed per instance, used as directory name.
-         * 2. Align execution context `when` to interval boundary → `alignedTs`.
-         * 3. Build entity key = `${symbol}_${alignedTs}`.
+         * 2. Align execution context `when` to interval boundary → `alignedMs`.
+         * 3. Build entity key from the key generator (receives `[symbol, alignedMs, ...rest]`).
          * 4. Try to read from `PersistIntervalAdapter` using (bucket, entityKey).
          * 5. On hit — return `null` (interval already fired).
          * 6. On miss — call `fn`. If non-null, write to disk and return result. If null, skip write and return null.
@@ -54377,12 +55507,13 @@ class IntervalFileInstance {
          * Requires active method context and execution context.
          *
          * @param symbol - Trading pair symbol (e.g. "BTCUSDT")
+         * @param args - Additional arguments forwarded to the wrapped function
          * @returns The value on the first non-null fire, `null` if already fired this interval
          *   or if `fn` itself returned `null`
          * @throws Error if method context, execution context, or interval is missing
          */
-        this.run = async (symbol) => {
-            backtest.loggerService.debug(INTERVAL_FILE_INSTANCE_METHOD_NAME_RUN, { symbol });
+        this.run = async (...args) => {
+            backtest.loggerService.debug(INTERVAL_FILE_INSTANCE_METHOD_NAME_RUN, { args });
             const step = INTERVAL_MINUTES[this.interval];
             {
                 if (!MethodContextService.hasContext()) {
@@ -54395,15 +55526,16 @@ class IntervalFileInstance {
                     throw new Error(`IntervalFileInstance unknown interval=${this.interval}`);
                 }
             }
+            const [symbol, ...rest] = args;
             const { when } = backtest.executionContextService.context;
-            const alignedTs = align(when.getTime(), this.interval);
+            const alignedMs = align(when.getTime(), this.interval);
             const bucket = `${this.name}_${this.interval}_${this.index}`;
-            const entityKey = `${symbol}_${alignedTs}`;
+            const entityKey = this.key([symbol, alignedMs, ...rest]);
             const cached = await PersistIntervalAdapter.readIntervalData(bucket, entityKey);
             if (cached !== null) {
                 return null;
             }
-            const result = await this.fn(symbol, when);
+            const result = await this.fn.call(null, ...args);
             if (result !== null) {
                 await PersistIntervalAdapter.writeIntervalData({ id: entityKey, data: result, removed: false }, bucket, entityKey);
             }
@@ -54444,12 +55576,12 @@ class IntervalUtils {
          * Memoized factory to get or create an `IntervalFnInstance` for a function.
          * Each function reference gets its own isolated instance.
          */
-        this._getInstance = memoize(([run]) => run, (run, interval) => new IntervalFnInstance(run, interval));
+        this._getInstance = memoize(([run]) => run, (run, interval, key) => new IntervalFnInstance(run, interval, key));
         /**
          * Memoized factory to get or create an `IntervalFileInstance` for an async function.
          * Each function reference gets its own isolated persistent instance.
          */
-        this._getFileInstance = memoize(([run]) => run, (run, interval, name) => new IntervalFileInstance(run, interval, name));
+        this._getFileInstance = memoize(([run]) => run, (run, interval, name, key) => new IntervalFileInstance(run, interval, name, key));
         /**
          * Wrap a signal function with in-memory once-per-interval firing.
          *
@@ -54461,21 +55593,30 @@ 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)
          * ```
          */
         this.fn = (run, context) => {
             backtest.loggerService.info(INTERVAL_METHOD_NAME_FN, { context });
-            const wrappedFn = (symbol) => {
-                const instance = this._getInstance(run, context.interval);
-                return instance.run(symbol);
+            const wrappedFn = (...args) => {
+                const instance = this._getInstance(run, context.interval, context.key);
+                return instance.run(...args);
             };
             wrappedFn.clear = () => {
                 backtest.loggerService.info(INTERVAL_METHOD_NAME_FN_CLEAR);
@@ -54489,6 +55630,14 @@ class IntervalUtils {
                 }
                 this._getInstance.get(run)?.clear();
             };
+            wrappedFn.gc = () => {
+                backtest.loggerService.info(INTERVAL_METHOD_NAME_FN_GC);
+                if (!ExecutionContextService.hasContext()) {
+                    backtest.loggerService.warn(`${INTERVAL_METHOD_NAME_FN_GC} called without execution context, skipping`);
+                    return;
+                }
+                return this._getInstance.get(run)?.gc();
+            };
             return wrappedFn;
         };
         /**
@@ -54501,28 +55650,33 @@ 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);
          * ```
          */
         this.file = (run, context) => {
             backtest.loggerService.info(INTERVAL_METHOD_NAME_FILE, { context });
             {
-                this._getFileInstance(run, context.interval, context.name);
+                this._getFileInstance(run, context.interval, context.name, context.key);
             }
-            const wrappedFn = (symbol) => {
-                const instance = this._getFileInstance(run, context.interval, context.name);
-                return instance.run(symbol);
+            const wrappedFn = (...args) => {
+                const instance = this._getFileInstance(run, context.interval, context.name, context.key);
+                return instance.run(...args);
             };
             wrappedFn.clear = async () => {
                 backtest.loggerService.info(INTERVAL_METHOD_NAME_FILE_CLEAR);
@@ -54548,10 +55702,10 @@ class IntervalUtils {
         this.dispose = (run) => {
             backtest.loggerService.info(INTERVAL_METHOD_NAME_DISPOSE, { run });
             this._getInstance.clear(run);
+            this._getFileInstance.clear(run);
         };
         /**
-         * 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.
          */
@@ -54559,7 +55713,15 @@ class IntervalUtils {
             backtest.loggerService.info(INTERVAL_METHOD_NAME_CLEAR);
             this._getInstance.clear();
             this._getFileInstance.clear();
-            IntervalFileInstance.clearCounter();
+        };
+        /**
+         * 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.
+         */
+        this.resetCounter = () => {
+            backtest.loggerService.info(INTERVAL_METHOD_NAME_RESET_COUNTER);
+            IntervalFileInstance.resetCounter();
         };
     }
 }
@@ -55693,4 +56855,4 @@ const validateSignal = (signal, currentPrice) => {
     return !errors.length;
 };
 
-export { ActionBase, Backtest, Breakeven, Broker, BrokerBase, Cache, Constant, Dump, Exchange, ExecutionContextService, Heat, HighestProfit, Interval, Live, Log, Markdown, MarkdownFileBase, MarkdownFolderBase, MarkdownWriter, MaxDrawdown, Memory, MethodContextService, Notification, NotificationBacktest, NotificationLive, Partial, Performance, PersistBase, PersistBreakevenAdapter, PersistCandleAdapter, PersistIntervalAdapter, PersistLogAdapter, PersistMeasureAdapter, PersistMemoryAdapter, PersistNotificationAdapter, PersistPartialAdapter, PersistRiskAdapter, PersistScheduleAdapter, PersistSignalAdapter, PersistStorageAdapter, Position, PositionSize, Report, ReportBase, ReportWriter, Risk, Schedule, Storage, StorageBacktest, StorageLive, Strategy, Sync, Walker, 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, Backtest, Breakeven, Broker, BrokerBase, Cache, Constant, Dump, Exchange, ExecutionContextService, Heat, HighestProfit, Interval, Live, Log, Markdown, MarkdownFileBase, MarkdownFolderBase, MarkdownWriter, MaxDrawdown, Memory, MethodContextService, Notification, NotificationBacktest, NotificationLive, Partial, Performance, PersistBase, PersistBreakevenAdapter, PersistCandleAdapter, PersistIntervalAdapter, PersistLogAdapter, PersistMeasureAdapter, PersistMemoryAdapter, PersistNotificationAdapter, PersistPartialAdapter, PersistRiskAdapter, PersistScheduleAdapter, PersistSignalAdapter, PersistStorageAdapter, Position, PositionSize, Reflect$1 as Reflect, Report, ReportBase, ReportWriter, Risk, Schedule, Storage, StorageBacktest, StorageLive, Strategy, Sync, Walker, 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 };