backtest-kit 9.0.0 → 9.0.1

package/build/index.cjs

@@ -938,7 +938,7 @@ const LOGGER_SERVICE$7 = new LoggerService();
 /** Symbol key for the singleshot waitForInit function on PersistBase instances. */
 const BASE_WAIT_FOR_INIT_SYMBOL = Symbol("wait-for-init");
 // Calculate step in milliseconds for candle close time validation
-const INTERVAL_MINUTES$9 = {
+const INTERVAL_MINUTES$a = {
     "1m": 1,
     "3m": 3,
     "5m": 5,
@@ -951,7 +951,7 @@ const INTERVAL_MINUTES$9 = {
     "8h": 480,
     "1d": 1440,
 };
-const MS_PER_MINUTE$7 = 60000;
+const MS_PER_MINUTE$8 = 60000;
 const PERSIST_SIGNAL_UTILS_METHOD_NAME_USE_PERSIST_SIGNAL_ADAPTER = "PersistSignalUtils.usePersistSignalAdapter";
 const PERSIST_SIGNAL_UTILS_METHOD_NAME_READ_DATA = "PersistSignalUtils.readSignalData";
 const PERSIST_SIGNAL_UTILS_METHOD_NAME_WRITE_DATA = "PersistSignalUtils.writeSignalData";
@@ -2276,7 +2276,7 @@ class PersistCandleInstance {
      * @returns Promise resolving to candles in order, or null on cache miss
      */
     async readCandlesData(limit, sinceTimestamp, _untilTimestamp) {
-        const stepMs = INTERVAL_MINUTES$9[this.interval] * MS_PER_MINUTE$7;
+        const stepMs = INTERVAL_MINUTES$a[this.interval] * MS_PER_MINUTE$8;
         const cachedCandles = [];
         for (let i = 0; i < limit; i++) {
             const expectedTimestamp = sinceTimestamp + i * stepMs;
@@ -2311,7 +2311,7 @@ class PersistCandleInstance {
      * @returns Promise that resolves when all writes are complete
      */
     async writeCandlesData(candles) {
-        const stepMs = INTERVAL_MINUTES$9[this.interval] * MS_PER_MINUTE$7;
+        const stepMs = INTERVAL_MINUTES$a[this.interval] * MS_PER_MINUTE$8;
         const now = Date.now();
         for (const candle of candles) {
             const candleCloseTime = candle.timestamp + stepMs;
@@ -3197,12 +3197,12 @@ class PersistMeasureUtils {
          * @param key - Cache key within the bucket
          * @returns Promise that resolves when write is complete
          */
-        this.writeMeasureData = async (data, bucket, key) => {
+        this.writeMeasureData = async (data, bucket, key, when) => {
             LOGGER_SERVICE$7.info(PERSIST_MEASURE_UTILS_METHOD_NAME_WRITE_DATA, { bucket, key });
             const isInitial = !this.getMeasureStorage.has(bucket);
             const instance = this.getMeasureStorage(bucket);
             await instance.waitForInit(isInitial);
-            return instance.writeMeasureData(data, key);
+            return instance.writeMeasureData(data, key, when);
         };
         /**
          * Soft-deletes a measure entry in the given bucket by setting `removed: true`.
@@ -3438,12 +3438,12 @@ class PersistIntervalUtils {
          * @param key - Marker key within the bucket
          * @returns Promise that resolves when write is complete
          */
-        this.writeIntervalData = async (data, bucket, key) => {
+        this.writeIntervalData = async (data, bucket, key, when) => {
             LOGGER_SERVICE$7.info(PERSIST_INTERVAL_UTILS_METHOD_NAME_WRITE_DATA, { bucket, key });
             const isInitial = !this.getIntervalStorage.has(bucket);
             const instance = this.getIntervalStorage(bucket);
             await instance.waitForInit(isInitial);
-            return instance.writeIntervalData(data, key);
+            return instance.writeIntervalData(data, key, when);
         };
         /**
          * Soft-deletes a marker in the given bucket by setting `removed: true`.
@@ -4629,8 +4629,8 @@ class CandleUtils {
 }
 const Candle = new CandleUtils();
 
-const MS_PER_MINUTE$6 = 60000;
-const INTERVAL_MINUTES$8 = {
+const MS_PER_MINUTE$7 = 60000;
+const INTERVAL_MINUTES$9 = {
     "1m": 1,
     "3m": 3,
     "5m": 5,
@@ -4661,7 +4661,7 @@ const INTERVAL_MINUTES$8 = {
  * @returns Aligned timestamp rounded down to interval boundary
  */
 const ALIGN_TO_INTERVAL_FN$2 = (timestamp, intervalMinutes) => {
-    const intervalMs = intervalMinutes * MS_PER_MINUTE$6;
+    const intervalMs = intervalMinutes * MS_PER_MINUTE$7;
     return Math.floor(timestamp / intervalMs) * intervalMs;
 };
 /**
@@ -4815,9 +4815,9 @@ const WRITE_CANDLES_CACHE_FN$1 = functoolsKit.trycatch(functoolsKit.queued(async
  * @returns Promise resolving to array of candle data
  */
 const GET_CANDLES_FN$1 = async (dto, since, self) => {
-    const step = INTERVAL_MINUTES$8[dto.interval];
+    const step = INTERVAL_MINUTES$9[dto.interval];
     const sinceTimestamp = since.getTime();
-    const untilTimestamp = sinceTimestamp + dto.limit * step * MS_PER_MINUTE$6;
+    const untilTimestamp = sinceTimestamp + dto.limit * step * MS_PER_MINUTE$7;
     await Candle.acquireLock(`ClientExchange GET_CANDLES_FN symbol=${dto.symbol} interval=${dto.interval} limit=${dto.limit}`);
     try {
         // Try to read from cache first
@@ -4931,11 +4931,11 @@ class ClientExchange {
             interval,
             limit,
         });
-        const step = INTERVAL_MINUTES$8[interval];
+        const step = INTERVAL_MINUTES$9[interval];
         if (!step) {
             throw new Error(`ClientExchange unknown interval=${interval}`);
         }
-        const stepMs = step * MS_PER_MINUTE$6;
+        const stepMs = step * MS_PER_MINUTE$7;
         // Align when down to interval boundary
         const whenTimestamp = this.params.execution.context.when.getTime();
         const alignedWhen = ALIGN_TO_INTERVAL_FN$2(whenTimestamp, step);
@@ -5012,11 +5012,11 @@ class ClientExchange {
         if (!this.params.execution.context.backtest) {
             throw new Error(`ClientExchange getNextCandles: cannot fetch future candles in live mode`);
         }
-        const step = INTERVAL_MINUTES$8[interval];
+        const step = INTERVAL_MINUTES$9[interval];
         if (!step) {
             throw new Error(`ClientExchange getNextCandles: unknown interval=${interval}`);
         }
-        const stepMs = step * MS_PER_MINUTE$6;
+        const stepMs = step * MS_PER_MINUTE$7;
         const now = Date.now();
         // Align when down to interval boundary
         const whenTimestamp = this.params.execution.context.when.getTime();
@@ -5201,11 +5201,11 @@ class ClientExchange {
             sDate,
             eDate,
         });
-        const step = INTERVAL_MINUTES$8[interval];
+        const step = INTERVAL_MINUTES$9[interval];
         if (!step) {
             throw new Error(`ClientExchange getRawCandles: unknown interval=${interval}`);
         }
-        const stepMs = step * MS_PER_MINUTE$6;
+        const stepMs = step * MS_PER_MINUTE$7;
         const whenTimestamp = this.params.execution.context.when.getTime();
         const alignedWhen = ALIGN_TO_INTERVAL_FN$2(whenTimestamp, step);
         let sinceTimestamp;
@@ -5334,7 +5334,7 @@ class ClientExchange {
         const alignedTo = ALIGN_TO_INTERVAL_FN$2(whenTimestamp, GLOBAL_CONFIG.CC_ORDER_BOOK_TIME_OFFSET_MINUTES);
         const to = new Date(alignedTo);
         const from = new Date(alignedTo -
-            GLOBAL_CONFIG.CC_ORDER_BOOK_TIME_OFFSET_MINUTES * MS_PER_MINUTE$6);
+            GLOBAL_CONFIG.CC_ORDER_BOOK_TIME_OFFSET_MINUTES * MS_PER_MINUTE$7);
         return await this.params.getOrderBook(symbol, depth, from, to, this.params.execution.context.backtest);
     }
     /**
@@ -5363,7 +5363,7 @@ class ClientExchange {
         const whenTimestamp = this.params.execution.context.when.getTime();
         // Align to 1-minute boundary to prevent look-ahead bias
         const alignedTo = ALIGN_TO_INTERVAL_FN$2(whenTimestamp, 1);
-        const windowMs = GLOBAL_CONFIG.CC_AGGREGATED_TRADES_MAX_MINUTES * MS_PER_MINUTE$6 - MS_PER_MINUTE$6;
+        const windowMs = GLOBAL_CONFIG.CC_AGGREGATED_TRADES_MAX_MINUTES * MS_PER_MINUTE$7 - MS_PER_MINUTE$7;
         // No limit: fetch a single window and return as-is
         if (limit === undefined) {
             const to = new Date(alignedTo);
@@ -6317,7 +6317,7 @@ const validateScheduledSignal = (signal, currentPrice) => {
     }
 };
 
-const INTERVAL_MINUTES$7 = {
+const INTERVAL_MINUTES$8 = {
     "1m": 1,
     "3m": 3,
     "5m": 5,
@@ -6738,7 +6738,7 @@ const GET_SIGNAL_FN = functoolsKit.trycatch(async (self) => {
     }
     const currentTime = self.params.execution.context.when.getTime();
     {
-        const intervalMinutes = INTERVAL_MINUTES$7[self.params.interval];
+        const intervalMinutes = INTERVAL_MINUTES$8[self.params.interval];
         const intervalMs = intervalMinutes * 60 * 1000;
         const alignedTime = Math.floor(currentTime / intervalMs) * intervalMs;
         // Проверяем что наступил новый интервал (по aligned timestamp)
@@ -13733,7 +13733,7 @@ class StrategyConnectionService {
  * Maps FrameInterval to minutes for timestamp calculation.
  * Used to generate timeframe arrays with proper spacing.
  */
-const INTERVAL_MINUTES$6 = {
+const INTERVAL_MINUTES$7 = {
     "1m": 1,
     "3m": 3,
     "5m": 5,
@@ -13787,7 +13787,7 @@ const GET_TIMEFRAME_FN = async (symbol, self) => {
         symbol,
     });
     const { interval, startDate, endDate } = self.params;
-    const intervalMinutes = INTERVAL_MINUTES$6[interval];
+    const intervalMinutes = INTERVAL_MINUTES$7[interval];
     if (!intervalMinutes) {
         throw new Error(`ClientFrame unknown interval: ${interval}`);
     }
@@ -14152,8 +14152,8 @@ const get = (object, path) => {
     return pathArrayFlat.reduce((obj, key) => obj && obj[key], object);
 };
 
-const MS_PER_MINUTE$5 = 60000;
-const INTERVAL_MINUTES$5 = {
+const MS_PER_MINUTE$6 = 60000;
+const INTERVAL_MINUTES$6 = {
     "1m": 1,
     "3m": 3,
     "5m": 5,
@@ -14184,11 +14184,11 @@ const INTERVAL_MINUTES$5 = {
  * @returns New Date aligned down to interval boundary
  */
 const alignToInterval = (date, interval) => {
-    const minutes = INTERVAL_MINUTES$5[interval];
+    const minutes = INTERVAL_MINUTES$6[interval];
     if (minutes === undefined) {
         throw new Error(`alignToInterval: unknown interval=${interval}`);
     }
-    const intervalMs = minutes * MS_PER_MINUTE$5;
+    const intervalMs = minutes * MS_PER_MINUTE$6;
     return new Date(Math.floor(date.getTime() / intervalMs) * intervalMs);
 };
 
@@ -19670,8 +19670,8 @@ class BacktestLogicPrivateService {
 }
 
 const EMITTER_CHECK_INTERVAL = 5000;
-const MS_PER_MINUTE$4 = 60000;
-const INTERVAL_MINUTES$4 = {
+const MS_PER_MINUTE$5 = 60000;
+const INTERVAL_MINUTES$5 = {
     "1m": 1,
     "3m": 3,
     "5m": 5,
@@ -19686,7 +19686,7 @@ const INTERVAL_MINUTES$4 = {
 };
 const createEmitter = functoolsKit.memoize(([interval]) => `${interval}`, (interval) => {
     const tickSubject = new functoolsKit.Subject();
-    const intervalMs = INTERVAL_MINUTES$4[interval] * MS_PER_MINUTE$4;
+    const intervalMs = INTERVAL_MINUTES$5[interval] * MS_PER_MINUTE$5;
     {
         let lastAligned = Math.floor(Date.now() / intervalMs) * intervalMs;
         functoolsKit.Source.fromInterval(EMITTER_CHECK_INTERVAL)
@@ -35192,7 +35192,7 @@ const EXCHANGE_METHOD_NAME_FORMAT_PRICE = "ExchangeUtils.formatPrice";
 const EXCHANGE_METHOD_NAME_GET_ORDER_BOOK = "ExchangeUtils.getOrderBook";
 const EXCHANGE_METHOD_NAME_GET_RAW_CANDLES = "ExchangeUtils.getRawCandles";
 const EXCHANGE_METHOD_NAME_GET_AGGREGATED_TRADES = "ExchangeUtils.getAggregatedTrades";
-const MS_PER_MINUTE$3 = 60000;
+const MS_PER_MINUTE$4 = 60000;
 /**
  * Gets current timestamp from execution context if available.
  * Returns current Date() if no execution context exists (non-trading GUI).
@@ -35259,7 +35259,7 @@ const DEFAULT_GET_ORDER_BOOK_FN = async (_symbol, _depth, _from, _to, _backtest)
 const DEFAULT_GET_AGGREGATED_TRADES_FN = async (_symbol, _from, _to, _backtest) => {
     throw new Error(`getAggregatedTrades is not implemented for this exchange`);
 };
-const INTERVAL_MINUTES$3 = {
+const INTERVAL_MINUTES$4 = {
     "1m": 1,
     "3m": 3,
     "5m": 5,
@@ -35290,7 +35290,7 @@ const INTERVAL_MINUTES$3 = {
  * @returns Aligned timestamp rounded down to interval boundary
  */
 const ALIGN_TO_INTERVAL_FN$1 = (timestamp, intervalMinutes) => {
-    const intervalMs = intervalMinutes * MS_PER_MINUTE$3;
+    const intervalMs = intervalMinutes * MS_PER_MINUTE$4;
     return Math.floor(timestamp / intervalMs) * intervalMs;
 };
 /**
@@ -35430,11 +35430,11 @@ class ExchangeInstance {
                 limit,
             });
             const getCandles = this._methods.getCandles;
-            const step = INTERVAL_MINUTES$3[interval];
+            const step = INTERVAL_MINUTES$4[interval];
             if (!step) {
                 throw new Error(`ExchangeInstance unknown interval=${interval}`);
             }
-            const stepMs = step * MS_PER_MINUTE$3;
+            const stepMs = step * MS_PER_MINUTE$4;
             // Align when down to interval boundary
             const when = await GET_TIMESTAMP_FN();
             const whenTimestamp = when.getTime();
@@ -35648,7 +35648,7 @@ class ExchangeInstance {
             const when = await GET_TIMESTAMP_FN();
             const alignedTo = ALIGN_TO_INTERVAL_FN$1(when.getTime(), GLOBAL_CONFIG.CC_ORDER_BOOK_TIME_OFFSET_MINUTES);
             const to = new Date(alignedTo);
-            const from = new Date(alignedTo - GLOBAL_CONFIG.CC_ORDER_BOOK_TIME_OFFSET_MINUTES * MS_PER_MINUTE$3);
+            const from = new Date(alignedTo - GLOBAL_CONFIG.CC_ORDER_BOOK_TIME_OFFSET_MINUTES * MS_PER_MINUTE$4);
             const isBacktest = await GET_BACKTEST_FN();
             return await this._methods.getOrderBook(symbol, depth, from, to, isBacktest);
         };
@@ -35680,7 +35680,7 @@ class ExchangeInstance {
             const when = await GET_TIMESTAMP_FN();
             // Align to 1-minute boundary to prevent look-ahead bias
             const alignedTo = ALIGN_TO_INTERVAL_FN$1(when.getTime(), 1);
-            const windowMs = GLOBAL_CONFIG.CC_AGGREGATED_TRADES_MAX_MINUTES * MS_PER_MINUTE$3 - MS_PER_MINUTE$3;
+            const windowMs = GLOBAL_CONFIG.CC_AGGREGATED_TRADES_MAX_MINUTES * MS_PER_MINUTE$4 - MS_PER_MINUTE$4;
             const isBacktest = await GET_BACKTEST_FN();
             // No limit: fetch a single window and return as-is
             if (limit === undefined) {
@@ -35743,11 +35743,11 @@ class ExchangeInstance {
                 sDate,
                 eDate,
             });
-            const step = INTERVAL_MINUTES$3[interval];
+            const step = INTERVAL_MINUTES$4[interval];
             if (!step) {
                 throw new Error(`ExchangeInstance getRawCandles: unknown interval=${interval}`);
             }
-            const stepMs = step * MS_PER_MINUTE$3;
+            const stepMs = step * MS_PER_MINUTE$4;
             const when = await GET_TIMESTAMP_FN();
             const nowTimestamp = when.getTime();
             const alignedNow = ALIGN_TO_INTERVAL_FN$1(nowTimestamp, step);
@@ -36059,8 +36059,8 @@ const Exchange = new ExchangeUtils();
 
 const WARM_CANDLES_METHOD_NAME = "cache.warmCandles";
 const CHECK_CANDLES_METHOD_NAME = "cache.checkCandles";
-const MS_PER_MINUTE$2 = 60000;
-const INTERVAL_MINUTES$2 = {
+const MS_PER_MINUTE$3 = 60000;
+const INTERVAL_MINUTES$3 = {
     "1m": 1,
     "3m": 3,
     "5m": 5,
@@ -36074,7 +36074,7 @@ const INTERVAL_MINUTES$2 = {
     "1d": 1440,
 };
 const ALIGN_TO_INTERVAL_FN = (timestamp, intervalMinutes) => {
-    const intervalMs = intervalMinutes * MS_PER_MINUTE$2;
+    const intervalMs = intervalMinutes * MS_PER_MINUTE$3;
     return Math.floor(timestamp / intervalMs) * intervalMs;
 };
 const BAR_LENGTH = 30;
@@ -36099,11 +36099,11 @@ const PRINT_PROGRESS_FN = (fetched, total, symbol, interval) => {
 async function checkCandles(params) {
     const { symbol, exchangeName, interval, from, to, baseDir = "./dump/data/candle" } = params;
     backtest.loggerService.info(CHECK_CANDLES_METHOD_NAME, params);
-    const step = INTERVAL_MINUTES$2[interval];
+    const step = INTERVAL_MINUTES$3[interval];
     if (!step) {
         throw new Error(`checkCandles: unsupported interval=${interval}`);
     }
-    const stepMs = step * MS_PER_MINUTE$2;
+    const stepMs = step * MS_PER_MINUTE$3;
     const dir = path.join(baseDir, exchangeName, symbol, interval);
     const fromTs = ALIGN_TO_INTERVAL_FN(from.getTime(), step);
     const toTs = ALIGN_TO_INTERVAL_FN(to.getTime(), step);
@@ -36173,11 +36173,11 @@ async function warmCandles(params) {
         from,
         to,
     });
-    const step = INTERVAL_MINUTES$2[interval];
+    const step = INTERVAL_MINUTES$3[interval];
     if (!step) {
         throw new Error(`warmCandles: unsupported interval=${interval}`);
     }
-    const stepMs = step * MS_PER_MINUTE$2;
+    const stepMs = step * MS_PER_MINUTE$3;
     const instance = new ExchangeInstance(exchangeName);
     const sinceTimestamp = ALIGN_TO_INTERVAL_FN(from.getTime(), step);
     const untilTimestamp = ALIGN_TO_INTERVAL_FN(to.getTime(), step);
@@ -48524,14 +48524,17 @@ class RecentPersistBacktestUtils {
         };
         /**
          * Retrieves the latest persisted signal for the given context.
+         * Returns null if the stored signal's `timestamp` is greater than the requested `when`
+         * (look-ahead bias protection).
          * @param symbol - Trading pair symbol
          * @param strategyName - Strategy identifier
          * @param exchangeName - Exchange identifier
          * @param frameName - Frame identifier
          * @param backtest - Flag indicating if the context is backtest or live
-         * @returns The latest signal or null if not found
+         * @param when - Logical timestamp at which the read is happening (look-ahead guard)
+         * @returns The latest signal or null if not found / shadowed by look-ahead
          */
-        this.getLatestSignal = async (symbol, strategyName, exchangeName, frameName, backtest$1) => {
+        this.getLatestSignal = async (symbol, strategyName, exchangeName, frameName, backtest$1, when) => {
             backtest.loggerService.info(RECENT_PERSIST_BACKTEST_METHOD_NAME_GET_LATEST_SIGNAL, {
                 symbol,
                 strategyName,
@@ -48539,20 +48542,26 @@ class RecentPersistBacktestUtils {
                 frameName,
                 backtest: backtest$1,
             });
-            return await PersistRecentAdapter.readRecentData(symbol, strategyName, exchangeName, frameName, backtest$1);
+            const signal = await PersistRecentAdapter.readRecentData(symbol, strategyName, exchangeName, frameName, backtest$1);
+            if (!signal || signal.timestamp > when.getTime()) {
+                return null;
+            }
+            return signal;
         };
         /**
          * Returns the number of whole minutes elapsed since the latest signal's creation timestamp.
-         * @param timestamp - Current timestamp in milliseconds
+         * `timestamp` doubles as the look-ahead cutoff — a signal whose `timestamp` exceeds
+         * the requested one is treated as not yet visible.
+         * @param timestamp - Current timestamp in milliseconds (also serves as look-ahead cutoff)
          * @param symbol - Trading pair symbol
          * @param strategyName - Strategy identifier
          * @param exchangeName - Exchange identifier
          * @param frameName - Frame identifier
          * @param backtest - Flag indicating if the context is backtest or live
-         * @returns Whole minutes since the latest signal was created, or null if no signal found
+         * @returns Whole minutes since the latest signal was created, or null if no signal found / shadowed by look-ahead
          */
         this.getMinutesSinceLatestSignalCreated = async (timestamp, symbol, strategyName, exchangeName, frameName, backtest) => {
-            const signal = await this.getLatestSignal(symbol, strategyName, exchangeName, frameName, backtest);
+            const signal = await this.getLatestSignal(symbol, strategyName, exchangeName, frameName, backtest, new Date(timestamp));
             if (!signal) {
                 return null;
             }
@@ -48588,30 +48597,39 @@ class RecentMemoryBacktestUtils {
         };
         /**
          * Retrieves the latest in-memory signal for the given context.
+         * Returns null if the stored signal's `timestamp` is greater than the requested `when`
+         * (look-ahead bias protection).
          * @param symbol - Trading pair symbol
          * @param strategyName - Strategy identifier
          * @param exchangeName - Exchange identifier
          * @param frameName - Frame identifier
          * @param backtest - Flag indicating if the context is backtest or live
-         * @returns The latest signal or null if not found
+         * @param when - Logical timestamp at which the read is happening (look-ahead guard)
+         * @returns The latest signal or null if not found / shadowed by look-ahead
          */
-        this.getLatestSignal = async (symbol, strategyName, exchangeName, frameName, backtest$1) => {
+        this.getLatestSignal = async (symbol, strategyName, exchangeName, frameName, backtest$1, when) => {
             const key = CREATE_KEY_FN$7(symbol, strategyName, exchangeName, frameName, backtest$1);
             backtest.loggerService.info(RECENT_MEMORY_BACKTEST_METHOD_NAME_GET_LATEST_SIGNAL, { key });
-            return this._signals.get(key) ?? null;
+            const signal = this._signals.get(key) ?? null;
+            if (!signal || signal.timestamp > when.getTime()) {
+                return null;
+            }
+            return signal;
         };
         /**
          * Returns the number of whole minutes elapsed since the latest signal's creation timestamp.
-         * @param timestamp - Current timestamp in milliseconds
+         * `timestamp` doubles as the look-ahead cutoff — a signal whose `timestamp` exceeds
+         * the requested one is treated as not yet visible.
+         * @param timestamp - Current timestamp in milliseconds (also serves as look-ahead cutoff)
          * @param symbol - Trading pair symbol
          * @param strategyName - Strategy identifier
          * @param exchangeName - Exchange identifier
          * @param frameName - Frame identifier
          * @param backtest - Flag indicating if the context is backtest or live
-         * @returns Whole minutes since the latest signal was created, or null if no signal found
+         * @returns Whole minutes since the latest signal was created, or null if no signal found / shadowed by look-ahead
          */
         this.getMinutesSinceLatestSignalCreated = async (timestamp, symbol, strategyName, exchangeName, frameName, backtest) => {
-            const signal = await this.getLatestSignal(symbol, strategyName, exchangeName, frameName, backtest);
+            const signal = await this.getLatestSignal(symbol, strategyName, exchangeName, frameName, backtest, new Date(timestamp));
             if (!signal) {
                 return null;
             }
@@ -48643,14 +48661,17 @@ class RecentPersistLiveUtils {
         };
         /**
          * Retrieves the latest persisted signal for the given context.
+         * Returns null if the stored signal's `timestamp` is greater than the requested `when`
+         * (look-ahead bias protection).
          * @param symbol - Trading pair symbol
          * @param strategyName - Strategy identifier
          * @param exchangeName - Exchange identifier
          * @param frameName - Frame identifier
          * @param backtest - Flag indicating if the context is backtest or live
-         * @returns The latest signal or null if not found
+         * @param when - Logical timestamp at which the read is happening (look-ahead guard)
+         * @returns The latest signal or null if not found / shadowed by look-ahead
          */
-        this.getLatestSignal = async (symbol, strategyName, exchangeName, frameName, backtest$1) => {
+        this.getLatestSignal = async (symbol, strategyName, exchangeName, frameName, backtest$1, when) => {
             backtest.loggerService.info(RECENT_PERSIST_LIVE_METHOD_NAME_GET_LATEST_SIGNAL, {
                 symbol,
                 strategyName,
@@ -48658,20 +48679,26 @@ class RecentPersistLiveUtils {
                 frameName,
                 backtest: backtest$1,
             });
-            return await PersistRecentAdapter.readRecentData(symbol, strategyName, exchangeName, frameName, backtest$1);
+            const signal = await PersistRecentAdapter.readRecentData(symbol, strategyName, exchangeName, frameName, backtest$1);
+            if (!signal || signal.timestamp > when.getTime()) {
+                return null;
+            }
+            return signal;
         };
         /**
          * Returns the number of whole minutes elapsed since the latest signal's creation timestamp.
-         * @param timestamp - Current timestamp in milliseconds
+         * `timestamp` doubles as the look-ahead cutoff — a signal whose `timestamp` exceeds
+         * the requested one is treated as not yet visible.
+         * @param timestamp - Current timestamp in milliseconds (also serves as look-ahead cutoff)
          * @param symbol - Trading pair symbol
          * @param strategyName - Strategy identifier
          * @param exchangeName - Exchange identifier
          * @param frameName - Frame identifier
          * @param backtest - Flag indicating if the context is backtest or live
-         * @returns Whole minutes since the latest signal was created, or null if no signal found
+         * @returns Whole minutes since the latest signal was created, or null if no signal found / shadowed by look-ahead
          */
         this.getMinutesSinceLatestSignalCreated = async (timestamp, symbol, strategyName, exchangeName, frameName, backtest) => {
-            const signal = await this.getLatestSignal(symbol, strategyName, exchangeName, frameName, backtest);
+            const signal = await this.getLatestSignal(symbol, strategyName, exchangeName, frameName, backtest, new Date(timestamp));
             if (!signal) {
                 return null;
             }
@@ -48707,30 +48734,39 @@ class RecentMemoryLiveUtils {
         };
         /**
          * Retrieves the latest in-memory signal for the given context.
+         * Returns null if the stored signal's `timestamp` is greater than the requested `when`
+         * (look-ahead bias protection).
          * @param symbol - Trading pair symbol
          * @param strategyName - Strategy identifier
          * @param exchangeName - Exchange identifier
          * @param frameName - Frame identifier
          * @param backtest - Flag indicating if the context is backtest or live
-         * @returns The latest signal or null if not found
+         * @param when - Logical timestamp at which the read is happening (look-ahead guard)
+         * @returns The latest signal or null if not found / shadowed by look-ahead
          */
-        this.getLatestSignal = async (symbol, strategyName, exchangeName, frameName, backtest$1) => {
+        this.getLatestSignal = async (symbol, strategyName, exchangeName, frameName, backtest$1, when) => {
             const key = CREATE_KEY_FN$7(symbol, strategyName, exchangeName, frameName, backtest$1);
             backtest.loggerService.info(RECENT_MEMORY_LIVE_METHOD_NAME_GET_LATEST_SIGNAL, { key });
-            return this._signals.get(key) ?? null;
+            const signal = this._signals.get(key) ?? null;
+            if (!signal || signal.timestamp > when.getTime()) {
+                return null;
+            }
+            return signal;
         };
         /**
          * Returns the number of whole minutes elapsed since the latest signal's creation timestamp.
-         * @param timestamp - Current timestamp in milliseconds
+         * `timestamp` doubles as the look-ahead cutoff — a signal whose `timestamp` exceeds
+         * the requested one is treated as not yet visible.
+         * @param timestamp - Current timestamp in milliseconds (also serves as look-ahead cutoff)
          * @param symbol - Trading pair symbol
          * @param strategyName - Strategy identifier
          * @param exchangeName - Exchange identifier
          * @param frameName - Frame identifier
          * @param backtest - Flag indicating if the context is backtest or live
-         * @returns Whole minutes since the latest signal was created, or null if no signal found
+         * @returns Whole minutes since the latest signal was created, or null if no signal found / shadowed by look-ahead
          */
         this.getMinutesSinceLatestSignalCreated = async (timestamp, symbol, strategyName, exchangeName, frameName, backtest) => {
-            const signal = await this.getLatestSignal(symbol, strategyName, exchangeName, frameName, backtest);
+            const signal = await this.getLatestSignal(symbol, strategyName, exchangeName, frameName, backtest, new Date(timestamp));
             if (!signal) {
                 return null;
             }
@@ -48770,9 +48806,10 @@ class RecentBacktestAdapter {
          * @param exchangeName - Exchange identifier
          * @param frameName - Frame identifier
          * @param backtest - Flag indicating if the context is backtest or live
-         * @returns The latest signal or null if not found
+         * @param when - Logical timestamp at which the read is happening (look-ahead guard)
+         * @returns The latest signal or null if not found / shadowed by look-ahead
          */
-        this.getLatestSignal = async (symbol, strategyName, exchangeName, frameName, backtest$1) => {
+        this.getLatestSignal = async (symbol, strategyName, exchangeName, frameName, backtest$1, when) => {
             backtest.loggerService.info(RECENT_BACKTEST_ADAPTER_METHOD_NAME_GET_LATEST_SIGNAL, {
                 symbol,
                 strategyName,
@@ -48780,18 +48817,20 @@ class RecentBacktestAdapter {
                 frameName,
                 backtest: backtest$1,
             });
-            return await this._recentBacktestUtils.getLatestSignal(symbol, strategyName, exchangeName, frameName, backtest$1);
+            return await this._recentBacktestUtils.getLatestSignal(symbol, strategyName, exchangeName, frameName, backtest$1, when);
         };
         /**
          * Returns the number of whole minutes elapsed since the latest signal's creation timestamp.
-         * Proxies call to the underlying storage adapter.
-         * @param timestamp - Current timestamp in milliseconds
+         * Proxies call to the underlying storage adapter. `timestamp` doubles as the
+         * look-ahead cutoff — a signal whose `timestamp` exceeds the requested one is
+         * treated as not yet visible.
+         * @param timestamp - Current timestamp in milliseconds (also serves as look-ahead cutoff)
          * @param symbol - Trading pair symbol
          * @param strategyName - Strategy identifier
          * @param exchangeName - Exchange identifier
          * @param frameName - Frame identifier
          * @param backtest - Flag indicating if the context is backtest or live
-         * @returns Whole minutes since the latest signal was created, or null if no signal found
+         * @returns Whole minutes since the latest signal was created, or null if no signal found / shadowed by look-ahead
          */
         this.getMinutesSinceLatestSignalCreated = async (timestamp, symbol, strategyName, exchangeName, frameName, backtest$1) => {
             backtest.loggerService.info(RECENT_BACKTEST_ADAPTER_METHOD_NAME_GET_LATEST_SIGNAL, {
@@ -48802,7 +48841,7 @@ class RecentBacktestAdapter {
                 backtest: backtest$1,
                 timestamp,
             });
-            const signal = await this._recentBacktestUtils.getLatestSignal(symbol, strategyName, exchangeName, frameName, backtest$1);
+            const signal = await this._recentBacktestUtils.getLatestSignal(symbol, strategyName, exchangeName, frameName, backtest$1, new Date(timestamp));
             if (!signal) {
                 return null;
             }
@@ -48874,9 +48913,10 @@ class RecentLiveAdapter {
          * @param exchangeName - Exchange identifier
          * @param frameName - Frame identifier
          * @param backtest - Flag indicating if the context is backtest or live
-         * @returns The latest signal or null if not found
+         * @param when - Logical timestamp at which the read is happening (look-ahead guard)
+         * @returns The latest signal or null if not found / shadowed by look-ahead
          */
-        this.getLatestSignal = async (symbol, strategyName, exchangeName, frameName, backtest$1) => {
+        this.getLatestSignal = async (symbol, strategyName, exchangeName, frameName, backtest$1, when) => {
             backtest.loggerService.info(RECENT_LIVE_ADAPTER_METHOD_NAME_GET_LATEST_SIGNAL, {
                 symbol,
                 strategyName,
@@ -48884,18 +48924,20 @@ class RecentLiveAdapter {
                 frameName,
                 backtest: backtest$1,
             });
-            return await this._recentLiveUtils.getLatestSignal(symbol, strategyName, exchangeName, frameName, backtest$1);
+            return await this._recentLiveUtils.getLatestSignal(symbol, strategyName, exchangeName, frameName, backtest$1, when);
         };
         /**
          * Returns the number of whole minutes elapsed since the latest signal's creation timestamp.
-         * Proxies call to the underlying storage adapter.
-         * @param timestamp - Current timestamp in milliseconds
+         * Proxies call to the underlying storage adapter. `timestamp` doubles as the
+         * look-ahead cutoff — a signal whose `timestamp` exceeds the requested one is
+         * treated as not yet visible.
+         * @param timestamp - Current timestamp in milliseconds (also serves as look-ahead cutoff)
          * @param symbol - Trading pair symbol
          * @param strategyName - Strategy identifier
          * @param exchangeName - Exchange identifier
          * @param frameName - Frame identifier
          * @param backtest - Flag indicating if the context is backtest or live
-         * @returns Whole minutes since the latest signal was created, or null if no signal found
+         * @returns Whole minutes since the latest signal was created, or null if no signal found / shadowed by look-ahead
          */
         this.getMinutesSinceLatestSignalCreated = async (timestamp, symbol, strategyName, exchangeName, frameName, backtest$1) => {
             backtest.loggerService.info(RECENT_LIVE_ADAPTER_METHOD_NAME_GET_LATEST_SIGNAL, {
@@ -48906,7 +48948,7 @@ class RecentLiveAdapter {
                 backtest: backtest$1,
                 timestamp,
             });
-            const signal = await this._recentLiveUtils.getLatestSignal(symbol, strategyName, exchangeName, frameName, backtest$1);
+            const signal = await this._recentLiveUtils.getLatestSignal(symbol, strategyName, exchangeName, frameName, backtest$1, new Date(timestamp));
             if (!signal) {
                 return null;
             }
@@ -48996,14 +49038,16 @@ class RecentAdapter {
         /**
          * Retrieves the latest active signal for the given symbol and context.
          * Searches backtest storage first, then live storage.
+         * Returns null if the stored signal's `timestamp` is greater than the requested `when`
+         * (look-ahead bias protection).
          *
          * @param symbol - Trading pair symbol
          * @param context - Execution context with strategyName, exchangeName, and frameName
-         * @param backtest - Flag indicating if the context is backtest or live
-         * @returns The latest signal or null if not found
+         * @param when - Logical timestamp at which the read is happening (look-ahead guard)
+         * @returns The latest signal or null if not found / shadowed by look-ahead
          * @throws Error if RecentAdapter is not enabled
          */
-        this.getLatestSignal = async (symbol, context) => {
+        this.getLatestSignal = async (symbol, context, when) => {
             backtest.loggerService.info(RECENT_ADAPTER_METHOD_NAME_GET_LATEST_SIGNAL, {
                 symbol,
                 context,
@@ -49012,10 +49056,10 @@ class RecentAdapter {
                 throw new Error("RecentAdapter is not enabled. Call enable() first.");
             }
             let result = null;
-            if (result = await RecentBacktest.getLatestSignal(symbol, context.strategyName, context.exchangeName, context.frameName, true)) {
+            if (result = await RecentBacktest.getLatestSignal(symbol, context.strategyName, context.exchangeName, context.frameName, true, when)) {
                 return result;
             }
-            if (result = await RecentLive.getLatestSignal(symbol, context.strategyName, context.exchangeName, context.frameName, false)) {
+            if (result = await RecentLive.getLatestSignal(symbol, context.strategyName, context.exchangeName, context.frameName, false, when)) {
                 return result;
             }
             return null;
@@ -49023,13 +49067,16 @@ class RecentAdapter {
         /**
          * Returns the number of whole minutes elapsed since the latest signal's creation timestamp.
          * Searches backtest storage first, then live storage.
-         * @param timestamp - Current timestamp in milliseconds
+         * `when` doubles as the look-ahead cutoff — a signal whose `timestamp` exceeds
+         * `when.getTime()` is treated as not yet visible — and as the "now" against
+         * which elapsed minutes are computed.
          * @param symbol - Trading pair symbol
          * @param context - Execution context with strategyName, exchangeName, and frameName
-         * @returns Whole minutes since the latest signal was created, or null if no signal found
+         * @param when - Logical timestamp at which the read is happening (look-ahead cutoff + "now")
+         * @returns Whole minutes since the latest signal was created, or null if no signal found / shadowed by look-ahead
          * @throws Error if RecentAdapter is not enabled
          */
-        this.getMinutesSinceLatestSignalCreated = async (symbol, context) => {
+        this.getMinutesSinceLatestSignalCreated = async (symbol, context, when) => {
             backtest.loggerService.info(RECENT_ADAPTER_METHOD_NAME_GET_MINUTES_SINCE_LATEST_SIGNAL, {
                 symbol,
                 context,
@@ -49038,13 +49085,11 @@ class RecentAdapter {
                 throw new Error("RecentAdapter is not enabled. Call enable() first.");
             }
             let signal = null;
-            if (signal = await RecentBacktest.getLatestSignal(symbol, context.strategyName, context.exchangeName, context.frameName, true)) {
-                const timestamp = await backtest.timeMetaService.getTimestamp(symbol, context, true);
-                return Math.floor((timestamp - signal.timestamp) / (1000 * 60));
+            if (signal = await RecentBacktest.getLatestSignal(symbol, context.strategyName, context.exchangeName, context.frameName, true, when)) {
+                return Math.floor((when.getTime() - signal.timestamp) / (1000 * 60));
             }
-            if (signal = await RecentLive.getLatestSignal(symbol, context.strategyName, context.exchangeName, context.frameName, false)) {
-                const timestamp = await backtest.timeMetaService.getTimestamp(symbol, context, false);
-                return Math.floor((timestamp - signal.timestamp) / (1000 * 60));
+            if (signal = await RecentLive.getLatestSignal(symbol, context.strategyName, context.exchangeName, context.frameName, false, when)) {
+                return Math.floor((when.getTime() - signal.timestamp) / (1000 * 60));
             }
             return null;
         };
@@ -49109,41 +49154,54 @@ class StateLocalInstance {
         this.initialValue = initialValue;
         this.signalId = signalId;
         this.bucketName = bucketName;
+        this._when = 0;
         /**
          * Initializes _value from initialValue - local state needs no async setup.
          * @returns Promise that resolves immediately
          */
         this.waitForInit = functoolsKit.singleshot(async (_initial) => {
             this._value = this.initialValue;
+            this._when = 0;
         });
         /**
          * Update the in-memory state value.
+         * Records `when` so future reads with a smaller `when` see `initialValue`.
+         * The dispatch updater receives the look-ahead-guarded current value.
          * @param dispatch - New value or updater function receiving current value
+         * @param when - Logical timestamp this value belongs to
          * @returns Updated state value
          */
-        this.setState = functoolsKit.queued(async (dispatch) => {
+        this.setState = functoolsKit.queued(async (dispatch, when) => {
             backtest.loggerService.debug(STATE_LOCAL_INSTANCE_METHOD_NAME_SET, {
                 signalId: this.signalId,
                 bucketName: this.bucketName,
             });
             if (typeof dispatch === "function") {
-                this._value = await dispatch(this._value);
+                const prev = this._when > when.getTime() ? this.initialValue : this._value;
+                this._value = await dispatch(prev);
             }
             else {
                 this._value = dispatch;
             }
+            this._when = when.getTime();
             return this._value;
         });
     }
     /**
      * Read the current in-memory state value.
+     * Returns `initialValue` when the stored `when` is greater than the requested `when`
+     * (look-ahead bias protection).
+     * @param when - Logical timestamp at which the read is happening
      * @returns Current state value
      */
-    async getState() {
+    async getState(when) {
         backtest.loggerService.debug(STATE_LOCAL_INSTANCE_METHOD_NAME_GET, {
             signalId: this.signalId,
             bucketName: this.bucketName,
         });
+        if (this._when > when.getTime()) {
+            return this.initialValue;
+        }
         return this._value;
     }
     /** Releases resources held by this instance. */
@@ -49177,14 +49235,14 @@ class StateDummyInstance {
      * No-op read - always returns initialValue.
      * @returns initialValue
      */
-    async getState() {
+    async getState(_when) {
         return this.initialValue;
     }
     /**
      * No-op write - discards the value and returns initialValue.
      * @returns initialValue
      */
-    async setState(_dispatch) {
+    async setState(_dispatch, _when) {
         return this.initialValue;
     }
     /** No-op. */
@@ -49210,6 +49268,7 @@ class StatePersistInstance {
         this.initialValue = initialValue;
         this.signalId = signalId;
         this.bucketName = bucketName;
+        this._when = 0;
         /**
          * Initialize persistence storage and restore state from disk.
          * @param initial - Whether this is the first initialization
@@ -49224,40 +49283,54 @@ class StatePersistInstance {
             const data = await PersistStateAdapter.readStateData(this.signalId, this.bucketName);
             if (data) {
                 this._value = data.data;
+                this._when = data.when;
                 return;
             }
             this._value = this.initialValue;
+            this._when = 0;
         });
         /**
          * Update state and persist to disk atomically.
+         * A write with a smaller `when` overwrites an existing record — that lets a
+         * restarted backtest reset live-written state without breaking live.
+         * The dispatch updater receives the look-ahead-guarded current value.
          * @param dispatch - New value or updater function receiving current value
+         * @param when - Logical timestamp this value belongs to
          * @returns Updated state value
          */
-        this.setState = functoolsKit.queued(async (dispatch) => {
+        this.setState = functoolsKit.queued(async (dispatch, when) => {
             backtest.loggerService.debug(STATE_PERSIST_INSTANCE_METHOD_NAME_SET, {
                 signalId: this.signalId,
                 bucketName: this.bucketName,
             });
             if (typeof dispatch === "function") {
-                this._value = await dispatch(this._value);
+                const prev = this._when > when.getTime() ? this.initialValue : this._value;
+                this._value = await dispatch(prev);
             }
             else {
                 this._value = dispatch;
             }
+            this._when = when.getTime();
             const id = CREATE_KEY_FN$6(this.signalId, this.bucketName);
-            await PersistStateAdapter.writeStateData({ id, data: this._value }, this.signalId, this.bucketName);
+            await PersistStateAdapter.writeStateData({ id, data: this._value, when: this._when }, this.signalId, this.bucketName);
             return this._value;
         });
     }
     /**
      * Read the current persisted state value.
+     * Returns `initialValue` when the stored `when` is greater than the requested `when`
+     * (look-ahead bias protection).
+     * @param when - Logical timestamp at which the read is happening
      * @returns Current state value
      */
-    async getState() {
+    async getState(when) {
         backtest.loggerService.debug(STATE_PERSIST_INSTANCE_METHOD_NAME_GET, {
             signalId: this.signalId,
             bucketName: this.bucketName,
         });
+        if (this._when > when.getTime()) {
+            return this.initialValue;
+        }
         return this._value;
     }
     /** Releases resources held by this instance. */
@@ -49310,6 +49383,7 @@ class StateBacktestAdapter {
          * @param dto.signalId - Signal identifier
          * @param dto.bucketName - Bucket name
          * @param dto.initialValue - Default value when no persisted state exists
+         * @param dto.when - Logical timestamp at which the read is happening (look-ahead guard)
          * @returns Current state value
          */
         this.getState = async (dto) => {
@@ -49321,7 +49395,7 @@ class StateBacktestAdapter {
             const isInitial = !this.getInstance.has(key);
             const instance = this.getInstance(dto.signalId, dto.bucketName, dto.initialValue);
             await instance.waitForInit(isInitial);
-            return await instance.getState();
+            return await instance.getState(dto.when);
         };
         /**
          * Update the state value for a signal.
@@ -49329,6 +49403,7 @@ class StateBacktestAdapter {
          * @param dto.signalId - Signal identifier
          * @param dto.bucketName - Bucket name
          * @param dto.initialValue - Default value when no persisted state exists
+         * @param dto.when - Logical timestamp this value belongs to
          * @returns Updated state value
          */
         this.setState = async (dispatch, dto) => {
@@ -49340,7 +49415,7 @@ class StateBacktestAdapter {
             const isInitial = !this.getInstance.has(key);
             const instance = this.getInstance(dto.signalId, dto.bucketName, dto.initialValue);
             await instance.waitForInit(isInitial);
-            return await instance.setState(dispatch);
+            return await instance.setState(dispatch, dto.when);
         };
         /**
          * Switches to in-memory adapter (default).
@@ -49425,6 +49500,7 @@ class StateLiveAdapter {
          * @param dto.signalId - Signal identifier
          * @param dto.bucketName - Bucket name
          * @param dto.initialValue - Default value when no persisted state exists
+         * @param dto.when - Logical timestamp at which the read is happening (look-ahead guard)
          * @returns Current state value
          */
         this.getState = async (dto) => {
@@ -49436,7 +49512,7 @@ class StateLiveAdapter {
             const isInitial = !this.getInstance.has(key);
             const instance = this.getInstance(dto.signalId, dto.bucketName, dto.initialValue);
             await instance.waitForInit(isInitial);
-            return await instance.getState();
+            return await instance.getState(dto.when);
         };
         /**
          * Update the state value for a signal.
@@ -49444,6 +49520,7 @@ class StateLiveAdapter {
          * @param dto.signalId - Signal identifier
          * @param dto.bucketName - Bucket name
          * @param dto.initialValue - Default value when no persisted state exists
+         * @param dto.when - Logical timestamp this value belongs to
          * @returns Updated state value
          */
         this.setState = async (dispatch, dto) => {
@@ -49455,7 +49532,7 @@ class StateLiveAdapter {
             const isInitial = !this.getInstance.has(key);
             const instance = this.getInstance(dto.signalId, dto.bucketName, dto.initialValue);
             await instance.waitForInit(isInitial);
-            return await instance.setState(dispatch);
+            return await instance.setState(dispatch, dto.when);
         };
         /**
          * Switches to in-memory adapter.
@@ -49552,6 +49629,7 @@ class StateAdapter {
          * @param dto.bucketName - Bucket name
          * @param dto.initialValue - Default value when no persisted state exists
          * @param dto.backtest - Flag indicating if the context is backtest or live
+         * @param dto.when - Logical timestamp at which the read is happening (look-ahead guard)
          * @returns Current state value
          * @throws Error if adapter is not enabled
          */
@@ -49577,6 +49655,7 @@ class StateAdapter {
          * @param dto.bucketName - Bucket name
          * @param dto.initialValue - Default value when no persisted state exists
          * @param dto.backtest - Flag indicating if the context is backtest or live
+         * @param dto.when - Logical timestamp this value belongs to
          * @returns Updated state value
          * @throws Error if adapter is not enabled
          */
@@ -49650,8 +49729,9 @@ async function getLatestSignal(symbol) {
     if (!MethodContextService.hasContext()) {
         throw new Error("getLatestSignal requires a method context");
     }
+    const { when } = backtest.executionContextService.context;
     const { exchangeName, frameName, strategyName } = backtest.methodContextService.context;
-    return await Recent.getLatestSignal(symbol, { exchangeName, frameName, strategyName });
+    return await Recent.getLatestSignal(symbol, { exchangeName, frameName, strategyName }, when);
 }
 /**
  * Returns the number of whole minutes elapsed since the latest signal's creation timestamp.
@@ -49686,8 +49766,9 @@ async function getMinutesSinceLatestSignalCreated(symbol) {
     if (!MethodContextService.hasContext()) {
         throw new Error("getMinutesSinceLatestSignalCreated requires a method context");
     }
+    const { when } = backtest.executionContextService.context;
     const { exchangeName, frameName, strategyName } = backtest.methodContextService.context;
-    return await Recent.getMinutesSinceLatestSignalCreated(symbol, { exchangeName, frameName, strategyName });
+    return await Recent.getMinutesSinceLatestSignalCreated(symbol, { exchangeName, frameName, strategyName }, when);
 }
 /**
  * Reads the state value scoped to the current active signal.
@@ -49732,7 +49813,7 @@ async function getSignalState(symbol, dto) {
     if (!MethodContextService.hasContext()) {
         throw new Error("getSignalState requires a method context");
     }
-    const { backtest: isBacktest } = backtest.executionContextService.context;
+    const { backtest: isBacktest, when } = backtest.executionContextService.context;
     const { exchangeName, frameName, strategyName } = backtest.methodContextService.context;
     const currentPrice = await backtest.exchangeConnectionService.getAveragePrice(symbol);
     let signal;
@@ -49742,6 +49823,7 @@ async function getSignalState(symbol, dto) {
             bucketName,
             initialValue,
             backtest: isBacktest,
+            when,
         });
     }
     if (signal = await backtest.strategyCoreService.getScheduledSignal(isBacktest, symbol, currentPrice, { exchangeName, frameName, strategyName })) {
@@ -49750,6 +49832,7 @@ async function getSignalState(symbol, dto) {
             bucketName,
             initialValue,
             backtest: isBacktest,
+            when,
         });
     }
     throw new Error(`getSignalState requires a pending or scheduled signal for symbol=${symbol} bucketName=${bucketName}`);
@@ -49801,7 +49884,7 @@ async function setSignalState(symbol, dispatch, dto) {
     if (!MethodContextService.hasContext()) {
         throw new Error("setSignalState requires a method context");
     }
-    const { backtest: isBacktest } = backtest.executionContextService.context;
+    const { backtest: isBacktest, when } = backtest.executionContextService.context;
     const { exchangeName, frameName, strategyName } = backtest.methodContextService.context;
     const currentPrice = await backtest.exchangeConnectionService.getAveragePrice(symbol);
     let signal;
@@ -49811,6 +49894,7 @@ async function setSignalState(symbol, dispatch, dto) {
             bucketName,
             initialValue,
             backtest: isBacktest,
+            when,
         });
     }
     if (signal = await backtest.strategyCoreService.getScheduledSignal(isBacktest, symbol, currentPrice, { exchangeName, frameName, strategyName })) {
@@ -49819,6 +49903,7 @@ async function setSignalState(symbol, dispatch, dto) {
             bucketName,
             initialValue,
             backtest: isBacktest,
+            when,
         });
     }
     throw new Error(`setSignalState requires a pending or scheduled signal for symbol=${symbol} bucketName=${bucketName}`);
@@ -49872,36 +49957,47 @@ class SessionLocalInstance {
         this.frameName = frameName;
         this.backtest = backtest$1;
         this._data = null;
+        this._when = 0;
         /**
          * Initializes _data to null — local session needs no async setup.
          * @returns Promise that resolves immediately
          */
         this.waitForInit = functoolsKit.singleshot(async (_initial) => {
             this._data = null;
+            this._when = 0;
         });
         /**
          * Read the current in-memory session value.
-         * @returns Current session value, or null if not set
+         * Returns null if the stored `when` is greater than the requested `when`
+         * (look-ahead bias protection).
+         * @param when - Logical timestamp at which the read is happening
+         * @returns Current session value, or null
          */
-        this.getData = async () => {
+        this.getData = async (when) => {
             backtest.loggerService.debug(SESSION_LOCAL_INSTANCE_METHOD_NAME_GET, {
                 strategyName: this.strategyName,
                 exchangeName: this.exchangeName,
                 frameName: this.frameName,
             });
+            if (this._when > when.getTime()) {
+                return null;
+            }
             return this._data;
         };
         /**
          * Update the in-memory session value.
+         * Records `when` so future reads with a smaller `when` see no value.
          * @param value - New value or null to clear
+         * @param when - Logical timestamp this value belongs to
          */
-        this.setData = async (value) => {
+        this.setData = async (value, when) => {
             backtest.loggerService.debug(SESSION_LOCAL_INSTANCE_METHOD_NAME_SET, {
                 strategyName: this.strategyName,
                 exchangeName: this.exchangeName,
                 frameName: this.frameName,
             });
             this._data = value;
+            this._when = when.getTime();
         };
     }
     /** Releases resources held by this instance. */
@@ -49937,13 +50033,13 @@ class SessionDummyInstance {
          * No-op read — always returns null.
          * @returns null
          */
-        this.getData = async () => {
+        this.getData = async (_when) => {
             return null;
         };
         /**
          * No-op write — discards the value.
          */
-        this.setData = async (_value) => {
+        this.setData = async (_value, _when) => {
         };
     }
     /** No-op. */
@@ -49969,6 +50065,7 @@ class SessionPersistInstance {
         this.frameName = frameName;
         this.backtest = backtest$1;
         this._data = null;
+        this._when = 0;
         /**
          * Initialize persistence storage and restore session from disk.
          * @param initial - Whether this is the first initialization
@@ -49984,35 +50081,47 @@ class SessionPersistInstance {
             const data = await PersistSessionAdapter.readSessionData(this.strategyName, this.exchangeName, this.frameName);
             if (data) {
                 this._data = data.data;
+                this._when = data.when;
                 return;
             }
             this._data = null;
+            this._when = 0;
         });
         /**
          * Read the current persisted session value.
-         * @returns Current session value, or null if not set
+         * Returns null if the stored `when` is greater than the requested `when`
+         * (look-ahead bias protection).
+         * @param when - Logical timestamp at which the read is happening
+         * @returns Current session value, or null
          */
-        this.getData = async () => {
+        this.getData = async (when) => {
             backtest.loggerService.debug(SESSION_PERSIST_INSTANCE_METHOD_NAME_GET, {
                 strategyName: this.strategyName,
                 exchangeName: this.exchangeName,
                 frameName: this.frameName,
             });
+            if (this._when > when.getTime()) {
+                return null;
+            }
             return this._data;
         };
         /**
          * Update session value and persist to disk atomically.
+         * A write with a smaller `when` overwrites an existing record — that lets
+         * a restarted backtest reset live-written state without breaking live.
          * @param value - New value or null to clear
+         * @param when - Logical timestamp this value belongs to
          */
-        this.setData = async (value) => {
+        this.setData = async (value, when) => {
             backtest.loggerService.debug(SESSION_PERSIST_INSTANCE_METHOD_NAME_SET, {
                 strategyName: this.strategyName,
                 exchangeName: this.exchangeName,
                 frameName: this.frameName,
             });
             this._data = value;
+            this._when = when.getTime();
             const id = CREATE_KEY_FN$5(this.symbol, this.strategyName, this.exchangeName, this.frameName, this.backtest);
-            await PersistSessionAdapter.writeSessionData({ id, data: value }, this.strategyName, this.exchangeName, this.frameName);
+            await PersistSessionAdapter.writeSessionData({ id, data: value, when: this._when }, this.strategyName, this.exchangeName, this.frameName);
         };
     }
     /** Releases resources held by this instance. */
@@ -50045,9 +50154,10 @@ class SessionBacktestAdapter {
          * @param context.strategyName - Strategy identifier
          * @param context.exchangeName - Exchange identifier
          * @param context.frameName - Frame identifier
-         * @returns Current session value, or null if not set
+         * @param when - Logical timestamp at which the read is happening (look-ahead guard)
+         * @returns Current session value, or null if not set / look-ahead
          */
-        this.getData = async (symbol, context) => {
+        this.getData = async (symbol, context, when) => {
             backtest.loggerService.debug(SESSION_BACKTEST_ADAPTER_METHOD_NAME_GET, {
                 strategyName: context.strategyName,
                 exchangeName: context.exchangeName,
@@ -50057,7 +50167,7 @@ class SessionBacktestAdapter {
             const isInitial = !this.getInstance.has(key);
             const instance = this.getInstance(symbol, context.strategyName, context.exchangeName, context.frameName, true);
             await instance.waitForInit(isInitial);
-            return await instance.getData();
+            return await instance.getData(when);
         };
         /**
          * Update the session value for a backtest run.
@@ -50066,8 +50176,9 @@ class SessionBacktestAdapter {
          * @param context.strategyName - Strategy identifier
          * @param context.exchangeName - Exchange identifier
          * @param context.frameName - Frame identifier
+         * @param when - Logical timestamp this value belongs to
          */
-        this.setData = async (symbol, value, context) => {
+        this.setData = async (symbol, value, context, when) => {
             backtest.loggerService.debug(SESSION_BACKTEST_ADAPTER_METHOD_NAME_SET, {
                 strategyName: context.strategyName,
                 exchangeName: context.exchangeName,
@@ -50077,7 +50188,7 @@ class SessionBacktestAdapter {
             const isInitial = !this.getInstance.has(key);
             const instance = this.getInstance(symbol, context.strategyName, context.exchangeName, context.frameName, true);
             await instance.waitForInit(isInitial);
-            return await instance.setData(value);
+            return await instance.setData(value, when);
         };
         /**
          * Switches to in-memory adapter (default).
@@ -50141,9 +50252,10 @@ class SessionLiveAdapter {
          * @param context.strategyName - Strategy identifier
          * @param context.exchangeName - Exchange identifier
          * @param context.frameName - Frame identifier
-         * @returns Current session value, or null if not set
+         * @param when - Logical timestamp at which the read is happening (look-ahead guard)
+         * @returns Current session value, or null if not set / look-ahead
          */
-        this.getData = async (symbol, context) => {
+        this.getData = async (symbol, context, when) => {
             backtest.loggerService.debug(SESSION_LIVE_ADAPTER_METHOD_NAME_GET, {
                 strategyName: context.strategyName,
                 exchangeName: context.exchangeName,
@@ -50153,7 +50265,7 @@ class SessionLiveAdapter {
             const isInitial = !this.getInstance.has(key);
             const instance = this.getInstance(symbol, context.strategyName, context.exchangeName, context.frameName, false);
             await instance.waitForInit(isInitial);
-            return await instance.getData();
+            return await instance.getData(when);
         };
         /**
          * Update the session value for a live run.
@@ -50162,8 +50274,9 @@ class SessionLiveAdapter {
          * @param context.strategyName - Strategy identifier
          * @param context.exchangeName - Exchange identifier
          * @param context.frameName - Frame identifier
+         * @param when - Logical timestamp this value belongs to
          */
-        this.setData = async (symbol, value, context) => {
+        this.setData = async (symbol, value, context, when) => {
             backtest.loggerService.debug(SESSION_LIVE_ADAPTER_METHOD_NAME_SET, {
                 strategyName: context.strategyName,
                 exchangeName: context.exchangeName,
@@ -50173,7 +50286,7 @@ class SessionLiveAdapter {
             const isInitial = !this.getInstance.has(key);
             const instance = this.getInstance(symbol, context.strategyName, context.exchangeName, context.frameName, false);
             await instance.waitForInit(isInitial);
-            return await instance.setData(value);
+            return await instance.setData(value, when);
         };
         /**
          * Switches to in-memory adapter.
@@ -50233,9 +50346,10 @@ class SessionAdapter {
          * @param context.exchangeName - Exchange identifier
          * @param context.frameName - Frame identifier
          * @param backtest - Flag indicating if the context is backtest or live
-         * @returns Current session value, or null if not set
+         * @param when - Logical timestamp at which the read is happening (look-ahead guard)
+         * @returns Current session value, or null if not set / look-ahead
          */
-        this.getData = async (symbol, context, backtest$1) => {
+        this.getData = async (symbol, context, backtest$1, when) => {
             backtest.loggerService.debug(SESSION_ADAPTER_METHOD_NAME_GET, {
                 strategyName: context.strategyName,
                 exchangeName: context.exchangeName,
@@ -50243,9 +50357,9 @@ class SessionAdapter {
                 backtest: backtest$1,
             });
             if (backtest$1) {
-                return await SessionBacktest.getData(symbol, context);
+                return await SessionBacktest.getData(symbol, context, when);
             }
-            return await SessionLive.getData(symbol, context);
+            return await SessionLive.getData(symbol, context, when);
         };
         /**
          * Update the session value for a signal.
@@ -50256,8 +50370,9 @@ class SessionAdapter {
          * @param context.exchangeName - Exchange identifier
          * @param context.frameName - Frame identifier
          * @param backtest - Flag indicating if the context is backtest or live
+         * @param when - Logical timestamp this value belongs to
          */
-        this.setData = async (symbol, value, context, backtest$1) => {
+        this.setData = async (symbol, value, context, backtest$1, when) => {
             backtest.loggerService.debug(SESSION_ADAPTER_METHOD_NAME_SET, {
                 strategyName: context.strategyName,
                 exchangeName: context.exchangeName,
@@ -50265,9 +50380,9 @@ class SessionAdapter {
                 backtest: backtest$1,
             });
             if (backtest$1) {
-                return await SessionBacktest.setData(symbol, value, context);
+                return await SessionBacktest.setData(symbol, value, context, when);
             }
-            return await SessionLive.setData(symbol, value, context);
+            return await SessionLive.setData(symbol, value, context, when);
         };
     }
 }
@@ -50319,9 +50434,9 @@ async function getSessionData(symbol) {
     if (!MethodContextService.hasContext()) {
         throw new Error("getSession requires a method context");
     }
-    const { backtest: isBacktest } = backtest.executionContextService.context;
+    const { backtest: isBacktest, when } = backtest.executionContextService.context;
     const { exchangeName, frameName, strategyName } = backtest.methodContextService.context;
-    return await Session.getData(symbol, { exchangeName, frameName, strategyName }, isBacktest);
+    return await Session.getData(symbol, { exchangeName, frameName, strategyName }, isBacktest, when);
 }
 /**
  * Writes a session value scoped to the current (symbol, strategy, exchange, frame) context.
@@ -50353,9 +50468,9 @@ async function setSessionData(symbol, value) {
     if (!MethodContextService.hasContext()) {
         throw new Error("setSession requires a method context");
     }
-    const { backtest: isBacktest } = backtest.executionContextService.context;
+    const { backtest: isBacktest, when } = backtest.executionContextService.context;
     const { exchangeName, frameName, strategyName } = backtest.methodContextService.context;
-    await Session.setData(symbol, value, { exchangeName, frameName, strategyName }, isBacktest);
+    await Session.setData(symbol, value, { exchangeName, frameName, strategyName }, isBacktest, when);
 }
 
 const CREATE_SIGNAL_STATE_METHOD_NAME = "state.createSignalState";
@@ -50366,7 +50481,7 @@ const CREATE_SET_STATE_FN = (params) => async (symbol, dispatch) => {
     if (!MethodContextService.hasContext()) {
         throw new Error("createSignalState requires a method context");
     }
-    const { backtest: isBacktest } = backtest.executionContextService.context;
+    const { backtest: isBacktest, when } = backtest.executionContextService.context;
     const { exchangeName, frameName, strategyName } = backtest.methodContextService.context;
     const currentPrice = await backtest.exchangeConnectionService.getAveragePrice(symbol);
     let signal;
@@ -50376,6 +50491,7 @@ const CREATE_SET_STATE_FN = (params) => async (symbol, dispatch) => {
             bucketName: params.bucketName,
             initialValue: params.initialValue,
             signalId: signal.id,
+            when,
         });
     }
     if (signal = await backtest.strategyCoreService.getScheduledSignal(isBacktest, symbol, currentPrice, { exchangeName, frameName, strategyName })) {
@@ -50384,6 +50500,7 @@ const CREATE_SET_STATE_FN = (params) => async (symbol, dispatch) => {
             bucketName: params.bucketName,
             initialValue: params.initialValue,
             signalId: signal.id,
+            when,
         });
     }
     throw new Error(`createSignalState requires a pending or scheduled signal for symbol=${symbol} bucketName=${params.bucketName}`);
@@ -50395,7 +50512,7 @@ const CREATE_GET_STATE_FN = (params) => async (symbol) => {
     if (!MethodContextService.hasContext()) {
         throw new Error("createSignalState requires a method context");
     }
-    const { backtest: isBacktest } = backtest.executionContextService.context;
+    const { backtest: isBacktest, when } = backtest.executionContextService.context;
     const { exchangeName, frameName, strategyName } = backtest.methodContextService.context;
     const currentPrice = await backtest.exchangeConnectionService.getAveragePrice(symbol);
     let signal;
@@ -50405,6 +50522,7 @@ const CREATE_GET_STATE_FN = (params) => async (symbol) => {
             bucketName: params.bucketName,
             initialValue: params.initialValue,
             signalId: signal.id,
+            when,
         });
     }
     if (signal = await backtest.strategyCoreService.getScheduledSignal(isBacktest, symbol, currentPrice, { exchangeName, frameName, strategyName })) {
@@ -50413,6 +50531,7 @@ const CREATE_GET_STATE_FN = (params) => async (symbol) => {
             bucketName: params.bucketName,
             initialValue: params.initialValue,
             signalId: signal.id,
+            when,
         });
     }
     throw new Error(`createSignalState requires a pending or scheduled signal for symbol=${symbol} bucketName=${params.bucketName}`);
@@ -50495,7 +50614,7 @@ const createSearchIndex = () => {
                 df.set(term, count);
         });
     };
-    const upsert = ({ id, content, index = JSON.stringify(content), priority = Date.now(), }) => {
+    const upsert = ({ id, content, when, index = JSON.stringify(content), priority = Date.now(), }) => {
         const existing = docs.get(id);
         {
             existing && subtractDf(existing.tf);
@@ -50504,12 +50623,21 @@ const createSearchIndex = () => {
         const tf = new Map();
         for (const t of tokens)
             tf.set(t, (tf.get(t) ?? 0) + 1);
-        docs.set(id, { tf, len: tokens.length, content, priority });
+        docs.set(id, { tf, len: tokens.length, content, priority, when });
         {
             addDf(tf);
         }
     };
-    const read = (id) => docs.get(id)?.content;
+    /**
+     * Read a document by id. Returns undefined when the document was written
+     * with a `when` greater than the requested `when` (look-ahead guard).
+     */
+    const read = (id, when) => {
+        const doc = docs.get(id);
+        if (!doc || doc.when > when)
+            return undefined;
+        return doc.content;
+    };
     const remove = (id) => {
         {
             const existing = docs.get(id);
@@ -50517,16 +50645,30 @@ const createSearchIndex = () => {
         }
         docs.delete(id);
     };
-    const list = () => Array.from(docs.entries())
+    /**
+     * List documents whose `when` is less than or equal to the requested `when`
+     * (look-ahead guard), sorted by priority.
+     */
+    const list = (when) => Array.from(docs.entries())
+        .filter(([, doc]) => doc.when <= when)
         .sort(([, a], [, b]) => a.priority - b.priority)
         .map(([id, { content }]) => ({ id, content }));
-    const search = (query, settings = DEFAULT_SETTINGS) => {
+    /**
+     * BM25 search over documents whose `when` is less than or equal to the
+     * requested `when` (look-ahead guard).
+     *
+     * Document frequency (df) is computed across the whole index — the time-cut
+     * is applied only to the candidate set, so scores stay comparable across
+     * different `when` values.
+     */
+    const search = (query, when, settings = DEFAULT_SETTINGS) => {
         const terms = tokenize(query);
         if (!terms.length || !docs.size)
             return [];
         const N = docs.size;
         const avgLen = [...docs.values()].reduce((s, d) => s + d.len, 0) / N;
         return [...docs.entries()]
+            .filter(([, doc]) => doc.when <= when)
             .map(([id, doc]) => {
             let score = 0;
             for (const term of terms) {
@@ -50623,8 +50765,9 @@ class MemoryLocalInstance {
      * @param memoryId - Unique entry identifier
      * @param value - Value to store and index
      * @param description - BM25 index string
+     * @param when - Logical timestamp this entry belongs to (look-ahead guard)
      */
-    async writeMemory(memoryId, value, description) {
+    async writeMemory(memoryId, value, description, when) {
         backtest.loggerService.debug(MEMORY_LOCAL_INSTANCE_METHOD_NAME_WRITE, {
             signalId: this.signalId,
             bucketName: this.bucketName,
@@ -50635,21 +50778,24 @@ class MemoryLocalInstance {
             content: value,
             index: description,
             priority: Date.now(),
+            when: when.getTime(),
         });
     }
     /**
      * Read a single entry from the in-memory index.
+     * Behaves as not-found if the stored `when` is greater than the requested `when`.
      * @param memoryId - Unique entry identifier
+     * @param when - Logical timestamp at which the read is happening (look-ahead guard)
      * @returns Parsed entry value
-     * @throws Error if entry not found
+     * @throws Error if entry not found (or shadowed by look-ahead)
      */
-    async readMemory(memoryId) {
+    async readMemory(memoryId, when) {
         backtest.loggerService.debug(MEMORY_LOCAL_INSTANCE_METHOD_NAME_READ, {
             signalId: this.signalId,
             bucketName: this.bucketName,
             memoryId,
         });
-        const value = this._index.read(memoryId);
+        const value = this._index.read(memoryId, when.getTime());
         if (!value) {
             throw new Error(`MemoryLocalInstance value not found memoryId=${memoryId}`);
         }
@@ -50657,33 +50803,38 @@ class MemoryLocalInstance {
     }
     /**
      * Search entries using BM25 full-text scoring.
+     * Filters out entries whose `when` is greater than the requested `when`.
      * @param query - Search query string
+     * @param when - Logical timestamp at which the search is happening (look-ahead guard)
      * @returns Matching entries sorted by relevance score
      */
-    async searchMemory(query, settings) {
+    async searchMemory(query, when, settings) {
         backtest.loggerService.debug(MEMORY_LOCAL_INSTANCE_METHOD_NAME_SEARCH, {
             signalId: this.signalId,
             bucketName: this.bucketName,
             query,
         });
-        return this._index.search(query, settings).map(SEARCH_MEMORY_FN);
+        return this._index.search(query, when.getTime(), settings).map(SEARCH_MEMORY_FN);
     }
     /**
      * List all entries stored in the in-memory index.
+     * Filters out entries whose `when` is greater than the requested `when`.
+     * @param when - Logical timestamp at which the list is happening (look-ahead guard)
      * @returns Array of all stored entries
      */
-    async listMemory() {
+    async listMemory(when) {
         backtest.loggerService.debug(MEMORY_LOCAL_INSTANCE_METHOD_NAME_LIST, {
             signalId: this.signalId,
             bucketName: this.bucketName,
         });
-        return this._index.list().map(LIST_MEMORY_FN);
+        return this._index.list(when.getTime()).map(LIST_MEMORY_FN);
     }
     /**
      * Remove an entry from the in-memory index.
      * @param memoryId - Unique entry identifier
+     * @param when - Logical timestamp (kept for API consistency; removal is by UUID)
      */
-    async removeMemory(memoryId) {
+    async removeMemory(memoryId, _when) {
         backtest.loggerService.debug(MEMORY_LOCAL_INSTANCE_METHOD_NAME_REMOVE, {
             signalId: this.signalId,
             bucketName: this.bucketName,
@@ -50729,12 +50880,13 @@ class MemoryPersistInstance {
             initial,
         });
         await PersistMemoryAdapter.waitForInit(this.signalId, this.bucketName, initial);
-        for await (const { memoryId, data: { data, index, priority } } of PersistMemoryAdapter.listMemoryData(this.signalId, this.bucketName)) {
+        for await (const { memoryId, data: { data, index, priority, when } } of PersistMemoryAdapter.listMemoryData(this.signalId, this.bucketName)) {
             this._index.upsert({
                 id: memoryId,
                 content: data,
                 index,
                 priority,
+                when,
             });
         }
     }
@@ -50743,69 +50895,79 @@ class MemoryPersistInstance {
      * @param memoryId - Unique entry identifier
      * @param value - Value to persist and index
      * @param index - BM25 index string; defaults to JSON.stringify(value)
+     * @param when - Logical timestamp this entry belongs to (look-ahead guard)
      */
-    async writeMemory(memoryId, value, index = JSON.stringify(value)) {
+    async writeMemory(memoryId, value, index, when) {
         backtest.loggerService.debug(MEMORY_PERSIST_INSTANCE_METHOD_NAME_WRITE, {
             signalId: this.signalId,
             bucketName: this.bucketName,
             memoryId,
         });
         const priority = Date.now();
-        await PersistMemoryAdapter.writeMemoryData({ data: value, priority, removed: false, index }, this.signalId, this.bucketName, memoryId);
+        const whenMs = when.getTime();
+        await PersistMemoryAdapter.writeMemoryData({ data: value, priority, removed: false, index, when: whenMs }, this.signalId, this.bucketName, memoryId);
         this._index.upsert({
             id: memoryId,
             content: value,
             index,
             priority,
+            when: whenMs,
         });
     }
     /**
      * Read a single entry from disk.
+     * Behaves as not-found if the stored `when` is greater than the requested `when`.
      * @param memoryId - Unique entry identifier
+     * @param when - Logical timestamp at which the read is happening (look-ahead guard)
      * @returns Entry value
-     * @throws Error if entry not found
+     * @throws Error if entry not found (or shadowed by look-ahead)
      */
-    async readMemory(memoryId) {
+    async readMemory(memoryId, when) {
         backtest.loggerService.debug(MEMORY_PERSIST_INSTANCE_METHOD_NAME_READ, {
             signalId: this.signalId,
             bucketName: this.bucketName,
             memoryId,
         });
         const data = await PersistMemoryAdapter.readMemoryData(this.signalId, this.bucketName, memoryId);
-        if (!data) {
+        if (!data || data.when > when.getTime()) {
             throw new Error(`MemoryPersistInstance value not found memoryId=${memoryId}`);
         }
         return data.data;
     }
     /**
      * Search entries using BM25 index rebuilt from disk on init.
+     * Filters out entries whose `when` is greater than the requested `when`.
      * @param query - Search query string
+     * @param when - Logical timestamp at which the search is happening (look-ahead guard)
      * @returns Matching entries sorted by relevance score
      */
-    async searchMemory(query, settings) {
+    async searchMemory(query, when, settings) {
         backtest.loggerService.debug(MEMORY_PERSIST_INSTANCE_METHOD_NAME_SEARCH, {
             signalId: this.signalId,
             bucketName: this.bucketName,
             query,
         });
-        return this._index.search(query, settings).map(SEARCH_MEMORY_FN);
+        return this._index.search(query, when.getTime(), settings).map(SEARCH_MEMORY_FN);
     }
     /**
      * List all entries from the in-memory index (populated from disk on init).
+     * Filters out entries whose `when` is greater than the requested `when`.
+     * @param when - Logical timestamp at which the list is happening (look-ahead guard)
      * @returns Array of all stored entries
      */
-    async listMemory() {
+    async listMemory(when) {
         backtest.loggerService.debug(MEMORY_PERSIST_INSTANCE_METHOD_NAME_LIST, {
             signalId: this.signalId,
             bucketName: this.bucketName,
         });
-        return this._index.list().map(LIST_MEMORY_FN);
+        return this._index.list(when.getTime()).map(LIST_MEMORY_FN);
     }
     /**
      * Remove an entry from disk and from the BM25 index.
      * @param memoryId - Unique entry identifier
+     * @param when - Logical timestamp (kept for API consistency; removal is by UUID)
      */
-    async removeMemory(memoryId) {
+    async removeMemory(memoryId, _when) {
         backtest.loggerService.debug(MEMORY_PERSIST_INSTANCE_METHOD_NAME_REMOVE, {
             signalId: this.signalId,
             bucketName: this.bucketName,
@@ -50842,34 +51004,34 @@ class MemoryDummyInstance {
      * No-op write - discards the value.
      * @returns Promise that resolves immediately
      */
-    async writeMemory() {
+    async writeMemory(_memoryId, _value, _description, _when) {
     }
     /**
      * No-op read - always throws.
      * @throws Error always
      */
-    async readMemory(_memoryId) {
+    async readMemory(_memoryId, _when) {
         throw new Error("MemoryDummyInstance: readMemory not supported");
     }
     /**
      * No-op search - returns empty array.
      * @returns Empty array
      */
-    async searchMemory() {
+    async searchMemory(_query, _when, _settings) {
         return [];
     }
     /**
      * No-op list - returns empty array.
      * @returns Empty array
      */
-    async listMemory() {
+    async listMemory(_when) {
         return [];
     }
     /**
      * No-op remove.
      * @returns Promise that resolves immediately
      */
-    async removeMemory() {
+    async removeMemory(_memoryId, _when) {
     }
     /** No-op. */
     dispose() {
@@ -50913,6 +51075,7 @@ class MemoryBacktestAdapter {
          * @param dto.signalId - Signal identifier
          * @param dto.bucketName - Bucket name
          * @param dto.description - BM25 index string; defaults to JSON.stringify(value)
+         * @param dto.when - Logical timestamp this entry belongs to (look-ahead guard)
          */
         this.writeMemory = async (dto) => {
             backtest.loggerService.debug(MEMORY_BACKTEST_ADAPTER_METHOD_NAME_WRITE, {
@@ -50924,13 +51087,14 @@ class MemoryBacktestAdapter {
             const isInitial = !this.getInstance.has(key);
             const instance = this.getInstance(dto.signalId, dto.bucketName);
             await instance.waitForInit(isInitial);
-            return await instance.writeMemory(dto.memoryId, dto.value, dto.description);
+            return await instance.writeMemory(dto.memoryId, dto.value, dto.description, dto.when);
         };
         /**
          * Search memory using BM25 full-text scoring.
          * @param dto.query - Search query string
          * @param dto.signalId - Signal identifier
          * @param dto.bucketName - Bucket name
+         * @param dto.when - Logical timestamp at which the search is happening (look-ahead guard)
          * @returns Matching entries sorted by relevance score
          */
         this.searchMemory = async (dto) => {
@@ -50943,12 +51107,13 @@ class MemoryBacktestAdapter {
             const isInitial = !this.getInstance.has(key);
             const instance = this.getInstance(dto.signalId, dto.bucketName);
             await instance.waitForInit(isInitial);
-            return await instance.searchMemory(dto.query, dto.settings);
+            return await instance.searchMemory(dto.query, dto.when, dto.settings);
         };
         /**
          * List all entries in memory.
          * @param dto.signalId - Signal identifier
          * @param dto.bucketName - Bucket name
+         * @param dto.when - Logical timestamp at which the list is happening (look-ahead guard)
          * @returns Array of all stored entries
          */
         this.listMemory = async (dto) => {
@@ -50960,13 +51125,14 @@ class MemoryBacktestAdapter {
             const isInitial = !this.getInstance.has(key);
             const instance = this.getInstance(dto.signalId, dto.bucketName);
             await instance.waitForInit(isInitial);
-            return await instance.listMemory();
+            return await instance.listMemory(dto.when);
         };
         /**
          * Remove an entry from memory.
          * @param dto.memoryId - Unique entry identifier
          * @param dto.signalId - Signal identifier
          * @param dto.bucketName - Bucket name
+         * @param dto.when - Logical timestamp (kept for API consistency; removal is by UUID)
          */
         this.removeMemory = async (dto) => {
             backtest.loggerService.debug(MEMORY_BACKTEST_ADAPTER_METHOD_NAME_REMOVE, {
@@ -50978,13 +51144,14 @@ class MemoryBacktestAdapter {
             const isInitial = !this.getInstance.has(key);
             const instance = this.getInstance(dto.signalId, dto.bucketName);
             await instance.waitForInit(isInitial);
-            return await instance.removeMemory(dto.memoryId);
+            return await instance.removeMemory(dto.memoryId, dto.when);
         };
         /**
          * Read a single entry from memory.
          * @param dto.memoryId - Unique entry identifier
          * @param dto.signalId - Signal identifier
          * @param dto.bucketName - Bucket name
+         * @param dto.when - Logical timestamp at which the read is happening (look-ahead guard)
          * @returns Entry value
          * @throws Error if entry not found
          */
@@ -50998,7 +51165,7 @@ class MemoryBacktestAdapter {
             const isInitial = !this.getInstance.has(key);
             const instance = this.getInstance(dto.signalId, dto.bucketName);
             await instance.waitForInit(isInitial);
-            return await instance.readMemory(dto.memoryId);
+            return await instance.readMemory(dto.memoryId, dto.when);
         };
         /**
          * Switches to in-memory BM25 adapter (default).
@@ -51080,6 +51247,7 @@ class MemoryLiveAdapter {
          * @param dto.signalId - Signal identifier
          * @param dto.bucketName - Bucket name
          * @param dto.description - BM25 index string; defaults to JSON.stringify(value)
+         * @param dto.when - Logical timestamp this entry belongs to (look-ahead guard)
          */
         this.writeMemory = async (dto) => {
             backtest.loggerService.debug(MEMORY_LIVE_ADAPTER_METHOD_NAME_WRITE, {
@@ -51091,13 +51259,14 @@ class MemoryLiveAdapter {
             const isInitial = !this.getInstance.has(key);
             const instance = this.getInstance(dto.signalId, dto.bucketName);
             await instance.waitForInit(isInitial);
-            return await instance.writeMemory(dto.memoryId, dto.value, dto.description);
+            return await instance.writeMemory(dto.memoryId, dto.value, dto.description, dto.when);
         };
         /**
          * Search memory using BM25 full-text scoring.
          * @param dto.query - Search query string
          * @param dto.signalId - Signal identifier
          * @param dto.bucketName - Bucket name
+         * @param dto.when - Logical timestamp at which the search is happening (look-ahead guard)
          * @returns Matching entries sorted by relevance score
          */
         this.searchMemory = async (dto) => {
@@ -51110,12 +51279,13 @@ class MemoryLiveAdapter {
             const isInitial = !this.getInstance.has(key);
             const instance = this.getInstance(dto.signalId, dto.bucketName);
             await instance.waitForInit(isInitial);
-            return await instance.searchMemory(dto.query, dto.settings);
+            return await instance.searchMemory(dto.query, dto.when, dto.settings);
         };
         /**
          * List all entries in memory.
          * @param dto.signalId - Signal identifier
          * @param dto.bucketName - Bucket name
+         * @param dto.when - Logical timestamp at which the list is happening (look-ahead guard)
          * @returns Array of all stored entries
          */
         this.listMemory = async (dto) => {
@@ -51127,13 +51297,14 @@ class MemoryLiveAdapter {
             const isInitial = !this.getInstance.has(key);
             const instance = this.getInstance(dto.signalId, dto.bucketName);
             await instance.waitForInit(isInitial);
-            return await instance.listMemory();
+            return await instance.listMemory(dto.when);
         };
         /**
          * Remove an entry from memory.
          * @param dto.memoryId - Unique entry identifier
          * @param dto.signalId - Signal identifier
          * @param dto.bucketName - Bucket name
+         * @param dto.when - Logical timestamp (kept for API consistency; removal is by UUID)
          */
         this.removeMemory = async (dto) => {
             backtest.loggerService.debug(MEMORY_LIVE_ADAPTER_METHOD_NAME_REMOVE, {
@@ -51145,13 +51316,14 @@ class MemoryLiveAdapter {
             const isInitial = !this.getInstance.has(key);
             const instance = this.getInstance(dto.signalId, dto.bucketName);
             await instance.waitForInit(isInitial);
-            return await instance.removeMemory(dto.memoryId);
+            return await instance.removeMemory(dto.memoryId, dto.when);
         };
         /**
          * Read a single entry from memory.
          * @param dto.memoryId - Unique entry identifier
          * @param dto.signalId - Signal identifier
          * @param dto.bucketName - Bucket name
+         * @param dto.when - Logical timestamp at which the read is happening (look-ahead guard)
          * @returns Entry value
          * @throws Error if entry not found
          */
@@ -51165,7 +51337,7 @@ class MemoryLiveAdapter {
             const isInitial = !this.getInstance.has(key);
             const instance = this.getInstance(dto.signalId, dto.bucketName);
             await instance.waitForInit(isInitial);
-            return await instance.readMemory(dto.memoryId);
+            return await instance.readMemory(dto.memoryId, dto.when);
         };
         /**
          * Switches to in-memory BM25 adapter.
@@ -51264,6 +51436,7 @@ class MemoryAdapter {
          * @param dto.bucketName - Bucket name
          * @param dto.description - BM25 index string; defaults to JSON.stringify(value)
          * @param dto.backtest - Flag indicating if the context is backtest or live
+         * @param dto.when - Logical timestamp this entry belongs to (look-ahead guard)
          */
         this.writeMemory = async (dto) => {
             if (!this.enable.hasValue()) {
@@ -51287,6 +51460,7 @@ class MemoryAdapter {
          * @param dto.signalId - Signal identifier
          * @param dto.bucketName - Bucket name
          * @param dto.backtest - Flag indicating if the context is backtest or live
+         * @param dto.when - Logical timestamp at which the search is happening (look-ahead guard)
          * @returns Matching entries sorted by relevance score
          */
         this.searchMemory = async (dto) => {
@@ -51310,6 +51484,7 @@ class MemoryAdapter {
          * @param dto.signalId - Signal identifier
          * @param dto.bucketName - Bucket name
          * @param dto.backtest - Flag indicating if the context is backtest or live
+         * @param dto.when - Logical timestamp at which the list is happening (look-ahead guard)
          * @returns Array of all stored entries
          */
         this.listMemory = async (dto) => {
@@ -51333,6 +51508,7 @@ class MemoryAdapter {
          * @param dto.signalId - Signal identifier
          * @param dto.bucketName - Bucket name
          * @param dto.backtest - Flag indicating if the context is backtest or live
+         * @param dto.when - Logical timestamp (kept for API consistency; removal is by UUID)
          */
         this.removeMemory = async (dto) => {
             if (!this.enable.hasValue()) {
@@ -51356,6 +51532,7 @@ class MemoryAdapter {
          * @param dto.signalId - Signal identifier
          * @param dto.bucketName - Bucket name
          * @param dto.backtest - Flag indicating if the context is backtest or live
+         * @param dto.when - Logical timestamp at which the read is happening (look-ahead guard)
          * @returns Entry value
          * @throws Error if entry not found
          */
@@ -51428,7 +51605,7 @@ async function writeMemory(dto) {
     if (!MethodContextService.hasContext()) {
         throw new Error("writeMemory requires a method context");
     }
-    const { backtest: isBacktest, symbol } = backtest.executionContextService.context;
+    const { backtest: isBacktest, symbol, when } = backtest.executionContextService.context;
     const { exchangeName, frameName, strategyName } = backtest.methodContextService.context;
     const currentPrice = await backtest.exchangeConnectionService.getAveragePrice(symbol);
     let signal;
@@ -51440,6 +51617,7 @@ async function writeMemory(dto) {
             bucketName,
             description,
             backtest: isBacktest,
+            when,
         });
         return;
     }
@@ -51451,6 +51629,7 @@ async function writeMemory(dto) {
             bucketName,
             description,
             backtest: isBacktest,
+            when,
         });
         return;
     }
@@ -51486,7 +51665,7 @@ async function readMemory(dto) {
     if (!MethodContextService.hasContext()) {
         throw new Error("readMemory requires a method context");
     }
-    const { backtest: isBacktest, symbol } = backtest.executionContextService.context;
+    const { backtest: isBacktest, symbol, when } = backtest.executionContextService.context;
     const { exchangeName, frameName, strategyName } = backtest.methodContextService.context;
     const currentPrice = await backtest.exchangeConnectionService.getAveragePrice(symbol);
     let signal;
@@ -51496,6 +51675,7 @@ async function readMemory(dto) {
             signalId: signal.id,
             bucketName,
             backtest: isBacktest,
+            when,
         });
     }
     if (signal = await backtest.strategyCoreService.getScheduledSignal(isBacktest, symbol, currentPrice, { exchangeName, frameName, strategyName })) {
@@ -51504,6 +51684,7 @@ async function readMemory(dto) {
             signalId: signal.id,
             bucketName,
             backtest: isBacktest,
+            when,
         });
     }
     throw new Error(`readMemory requires a pending or scheduled signal for symbol=${symbol} memoryId=${memoryId}`);
@@ -51538,7 +51719,7 @@ async function searchMemory(dto) {
     if (!MethodContextService.hasContext()) {
         throw new Error("searchMemory requires a method context");
     }
-    const { backtest: isBacktest, symbol } = backtest.executionContextService.context;
+    const { backtest: isBacktest, symbol, when } = backtest.executionContextService.context;
     const { exchangeName, frameName, strategyName } = backtest.methodContextService.context;
     const currentPrice = await backtest.exchangeConnectionService.getAveragePrice(symbol);
     let signal;
@@ -51548,6 +51729,7 @@ async function searchMemory(dto) {
             signalId: signal.id,
             bucketName,
             backtest: isBacktest,
+            when,
         });
     }
     if (signal = await backtest.strategyCoreService.getScheduledSignal(isBacktest, symbol, currentPrice, { exchangeName, frameName, strategyName })) {
@@ -51556,6 +51738,7 @@ async function searchMemory(dto) {
             signalId: signal.id,
             bucketName,
             backtest: isBacktest,
+            when,
         });
     }
     throw new Error(`searchMemory requires a pending or scheduled signal for symbol=${symbol} query=${query}`);
@@ -51588,7 +51771,7 @@ async function listMemory(dto) {
     if (!MethodContextService.hasContext()) {
         throw new Error("listMemory requires a method context");
     }
-    const { backtest: isBacktest, symbol } = backtest.executionContextService.context;
+    const { backtest: isBacktest, symbol, when } = backtest.executionContextService.context;
     const { exchangeName, frameName, strategyName } = backtest.methodContextService.context;
     const currentPrice = await backtest.exchangeConnectionService.getAveragePrice(symbol);
     let signal;
@@ -51597,6 +51780,7 @@ async function listMemory(dto) {
             signalId: signal.id,
             bucketName,
             backtest: isBacktest,
+            when,
         });
     }
     if (signal = await backtest.strategyCoreService.getScheduledSignal(isBacktest, symbol, currentPrice, { exchangeName, frameName, strategyName })) {
@@ -51604,6 +51788,7 @@ async function listMemory(dto) {
             signalId: signal.id,
             bucketName,
             backtest: isBacktest,
+            when,
         });
     }
     throw new Error(`listMemory requires a pending or scheduled signal for symbol=${symbol} bucketName=${bucketName}`);
@@ -51638,7 +51823,7 @@ async function removeMemory(dto) {
     if (!MethodContextService.hasContext()) {
         throw new Error("removeMemory requires a method context");
     }
-    const { backtest: isBacktest, symbol } = backtest.executionContextService.context;
+    const { backtest: isBacktest, symbol, when } = backtest.executionContextService.context;
     const { exchangeName, frameName, strategyName } = backtest.methodContextService.context;
     const currentPrice = await backtest.exchangeConnectionService.getAveragePrice(symbol);
     let signal;
@@ -51648,6 +51833,7 @@ async function removeMemory(dto) {
             signalId: signal.id,
             bucketName,
             backtest: isBacktest,
+            when,
         });
         return;
     }
@@ -51657,6 +51843,7 @@ async function removeMemory(dto) {
             signalId: signal.id,
             bucketName,
             backtest: isBacktest,
+            when,
         });
         return;
     }
@@ -51922,6 +52109,9 @@ class DumpMemoryInstance {
             value: { messages },
             description,
             backtest: this.backtest,
+            // when=0: dumps are UI artifacts (agent transcripts, markdown reports);
+            // they must stay visible regardless of the reader's logical time.
+            when: new Date(0)
         });
     }
     /**
@@ -51944,6 +52134,7 @@ class DumpMemoryInstance {
             value: record,
             description,
             backtest: this.backtest,
+            when: new Date(0)
         });
     }
     /**
@@ -51967,6 +52158,7 @@ class DumpMemoryInstance {
             value: { rows },
             description,
             backtest: this.backtest,
+            when: new Date(0)
         });
     }
     /**
@@ -51989,6 +52181,7 @@ class DumpMemoryInstance {
             value: { content },
             description,
             backtest: this.backtest,
+            when: new Date(0)
         });
     }
     /**
@@ -52011,6 +52204,7 @@ class DumpMemoryInstance {
             value: { content },
             description,
             backtest: this.backtest,
+            when: new Date(0)
         });
     }
     /**
@@ -52034,6 +52228,7 @@ class DumpMemoryInstance {
             value: json,
             description,
             backtest: this.backtest,
+            when: new Date(0)
         });
     }
     /** Releases resources held by this instance. */
@@ -60995,8 +61190,8 @@ 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 CACHE_FILE_INSTANCE_METHOD_NAME_HAS_VALUE = "CacheFileInstance.hasValue";
-const MS_PER_MINUTE$1 = 60000;
-const INTERVAL_MINUTES$1 = {
+const MS_PER_MINUTE$2 = 60000;
+const INTERVAL_MINUTES$2 = {
     "1m": 1,
     "3m": 3,
     "5m": 5,
@@ -61030,11 +61225,11 @@ const INTERVAL_MINUTES$1 = {
  * ```
  */
 const align$1 = (timestamp, interval) => {
-    const intervalMinutes = INTERVAL_MINUTES$1[interval];
+    const intervalMinutes = INTERVAL_MINUTES$2[interval];
     if (!intervalMinutes) {
         throw new Error(`align: unknown interval=${interval}`);
     }
-    const intervalMs = intervalMinutes * MS_PER_MINUTE$1;
+    const intervalMs = intervalMinutes * MS_PER_MINUTE$2;
     return Math.floor(timestamp / intervalMs) * intervalMs;
 };
 /**
@@ -61123,7 +61318,7 @@ class CacheFnInstance {
          */
         this.run = (...args) => {
             backtest.loggerService.debug(CACHE_METHOD_NAME_RUN, { args });
-            const step = INTERVAL_MINUTES$1[this.interval];
+            const step = INTERVAL_MINUTES$2[this.interval];
             {
                 if (!MethodContextService.hasContext()) {
                     throw new Error("CacheFnInstance run requires method context");
@@ -61318,7 +61513,7 @@ class CacheFileInstance {
          */
         this.run = async (...args) => {
             backtest.loggerService.debug(CACHE_FILE_INSTANCE_METHOD_NAME_RUN, { args });
-            const step = INTERVAL_MINUTES$1[this.interval];
+            const step = INTERVAL_MINUTES$2[this.interval];
             {
                 if (!MethodContextService.hasContext()) {
                     throw new Error("CacheFileInstance run requires method context");
@@ -61340,7 +61535,7 @@ class CacheFileInstance {
                 return cached.data;
             }
             const result = await this.fn.call(null, ...args);
-            await PersistMeasureAdapter.writeMeasureData({ id: entityKey, data: result, removed: false }, bucket, entityKey);
+            await PersistMeasureAdapter.writeMeasureData({ id: entityKey, data: result, removed: false }, bucket, entityKey, when);
             return result;
         };
         /**
@@ -61629,8 +61824,8 @@ const INTERVAL_METHOD_NAME_FILE_HAS_VALUE = "IntervalUtils.file.hasValue";
 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 = {
+const MS_PER_MINUTE$1 = 60000;
+const INTERVAL_MINUTES$1 = {
     "1m": 1,
     "3m": 3,
     "5m": 5,
@@ -61660,11 +61855,11 @@ const INTERVAL_MINUTES = {
  * ```
  */
 const align = (timestamp, interval) => {
-    const intervalMinutes = INTERVAL_MINUTES[interval];
+    const intervalMinutes = INTERVAL_MINUTES$1[interval];
     if (!intervalMinutes) {
         throw new Error(`align: unknown interval=${interval}`);
     }
-    const intervalMs = intervalMinutes * MS_PER_MINUTE;
+    const intervalMs = intervalMinutes * MS_PER_MINUTE$1;
     return Math.floor(timestamp / intervalMs) * intervalMs;
 };
 /**
@@ -61739,7 +61934,7 @@ class IntervalFnInstance {
          */
         this.run = (...args) => {
             backtest.loggerService.debug(INTERVAL_METHOD_NAME_RUN, { args });
-            const step = INTERVAL_MINUTES[this.interval];
+            const step = INTERVAL_MINUTES$1[this.interval];
             {
                 if (!MethodContextService.hasContext()) {
                     throw new Error("IntervalFnInstance run requires method context");
@@ -61906,7 +62101,7 @@ class IntervalFileInstance {
          */
         this.run = async (...args) => {
             backtest.loggerService.debug(INTERVAL_FILE_INSTANCE_METHOD_NAME_RUN, { args });
-            const step = INTERVAL_MINUTES[this.interval];
+            const step = INTERVAL_MINUTES$1[this.interval];
             {
                 if (!MethodContextService.hasContext()) {
                     throw new Error("IntervalFileInstance run requires method context");
@@ -61929,7 +62124,7 @@ class IntervalFileInstance {
             }
             const result = await this.fn.call(null, ...args);
             if (result !== null) {
-                await PersistIntervalAdapter.writeIntervalData({ id: entityKey, data: result, removed: false }, bucket, entityKey);
+                await PersistIntervalAdapter.writeIntervalData({ id: entityKey, data: result, when, removed: false }, bucket, entityKey, when);
             }
             return result;
         };
@@ -63053,6 +63248,31 @@ class ActionBase {
 // @ts-ignore
 ActionBase = functoolsKit.makeExtendable(ActionBase);
 
+const MS_PER_MINUTE = 60000;
+const INTERVAL_MINUTES = {
+    "1m": 1,
+    "3m": 3,
+    "5m": 5,
+    "15m": 15,
+    "30m": 30,
+    "1h": 60,
+    "2h": 120,
+    "4h": 240,
+    "6h": 360,
+    "8h": 480,
+    "1d": 1440,
+};
+/**
+ * Returns the step in milliseconds for a given candle interval.
+ * For example, for "15m" interval, it returns 900000 (15 * 60 * 1000).
+ *
+ * @param interval - Candle interval (e.g., "1m", "15m", "1h")
+ * @returns Step in milliseconds corresponding to the interval
+ */
+const intervalStepMs = (interval) => {
+    return INTERVAL_MINUTES[interval] * MS_PER_MINUTE;
+};
+
 /**
  * Rounds a price to the appropriate precision based on the tick size.
  *
@@ -63511,6 +63731,7 @@ exports.getWalkerSchema = getWalkerSchema;
 exports.hasNoPendingSignal = hasNoPendingSignal;
 exports.hasNoScheduledSignal = hasNoScheduledSignal;
 exports.hasTradeContext = hasTradeContext;
+exports.intervalStepMs = intervalStepMs;
 exports.investedCostToPercent = investedCostToPercent;
 exports.lib = backtest;
 exports.listExchangeSchema = listExchangeSchema;