backtest-kit 9.0.0 → 9.0.2

package/build/index.mjs

@@ -918,7 +918,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,
@@ -931,7 +931,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";
@@ -2256,7 +2256,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;
@@ -2291,7 +2291,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;
@@ -3177,12 +3177,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`.
@@ -3418,12 +3418,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`.
@@ -3561,7 +3561,7 @@ class PersistMemoryInstance {
      * @param memoryId - Memory entry identifier
      * @returns Promise that resolves when write is complete
      */
-    async writeMemoryData(data, memoryId) {
+    async writeMemoryData(data, memoryId, _when) {
         await this._storage.writeValue(memoryId, data);
     }
     /**
@@ -3626,7 +3626,7 @@ class PersistMemoryDummyInstance {
      * No-op write (discards entry).
      * @returns Promise that resolves immediately
      */
-    async writeMemoryData(_data, _memoryId) { }
+    async writeMemoryData(_data, _memoryId, _when) { }
     /**
      * No-op remove.
      * @returns Promise that resolves immediately
@@ -3719,19 +3719,20 @@ class PersistMemoryUtils {
          * Writes a memory entry for the given context.
          * Lazily initializes the instance on first access.
          *
-         * @param data - Entry data to persist
+         * @param data - Entry data to persist (already carries `data.when`)
          * @param signalId - Signal identifier
          * @param bucketName - Bucket name
          * @param memoryId - Memory entry identifier
+         * @param when - Logical timestamp this entry belongs to (duplicates `data.when` for API consistency)
          * @returns Promise that resolves when write is complete
          */
-        this.writeMemoryData = async (data, signalId, bucketName, memoryId) => {
+        this.writeMemoryData = async (data, signalId, bucketName, memoryId, when) => {
             LOGGER_SERVICE$7.info(PERSIST_MEMORY_UTILS_METHOD_NAME_WRITE_DATA, { signalId, bucketName, memoryId });
             const key = `${signalId}:${bucketName}`;
             const isInitial = !this.getMemoryStorage.has(key);
             const instance = this.getMemoryStorage(signalId, bucketName);
             await instance.waitForInit(isInitial);
-            return instance.writeMemoryData(data, memoryId);
+            return instance.writeMemoryData(data, memoryId, when);
         };
         /**
          * Soft-deletes a memory entry for the given context.
@@ -3895,7 +3896,7 @@ class PersistRecentInstance {
      * @param signalRow - Recent signal data to persist
      * @returns Promise that resolves when write is complete
      */
-    async writeRecentData(signalRow) {
+    async writeRecentData(signalRow, _when) {
         await this._storage.writeValue(this.symbol, signalRow);
     }
 }
@@ -3923,7 +3924,7 @@ class PersistRecentDummyInstance {
      * No-op write (discards recent signal).
      * @returns Promise that resolves immediately
      */
-    async writeRecentData(_signalRow) { }
+    async writeRecentData(_signalRow, _when) { }
 }
 /**
  * Utility class for managing recent signal persistence.
@@ -3970,21 +3971,22 @@ class PersistRecentUtils {
          * Writes the latest recent signal for the given context.
          * Lazily initializes the instance on first access.
          *
-         * @param signalRow - Recent signal data to persist
+         * @param signalRow - Recent signal data to persist (already carries `signalRow.timestamp`)
          * @param symbol - Trading pair symbol
          * @param strategyName - Strategy identifier
          * @param exchangeName - Exchange identifier
          * @param frameName - Frame identifier (may be empty)
          * @param backtest - True for backtest mode, false for live mode
+         * @param when - Logical timestamp this signal belongs to (duplicates `signalRow.timestamp` for API consistency)
          * @returns Promise that resolves when write is complete
          */
-        this.writeRecentData = async (signalRow, symbol, strategyName, exchangeName, frameName, backtest) => {
+        this.writeRecentData = async (signalRow, symbol, strategyName, exchangeName, frameName, backtest, when) => {
             LOGGER_SERVICE$7.info(PERSIST_RECENT_UTILS_METHOD_NAME_WRITE_DATA);
             const key = this.createKey(symbol, strategyName, exchangeName, frameName, backtest);
             const isInitial = !this.getStorage.has(key);
             const instance = this.getStorage(symbol, strategyName, exchangeName, frameName, backtest);
             await instance.waitForInit(isInitial);
-            return instance.writeRecentData(signalRow);
+            return instance.writeRecentData(signalRow, when);
         };
     }
     /**
@@ -4098,7 +4100,7 @@ class PersistStateInstance {
      * @param data - State data to persist
      * @returns Promise that resolves when write is complete
      */
-    async writeStateData(data) {
+    async writeStateData(data, _when) {
         await this._storage.writeValue(this.bucketName, data);
     }
     /**
@@ -4131,7 +4133,7 @@ class PersistStateDummyInstance {
      * No-op write (discards state).
      * @returns Promise that resolves immediately
      */
-    async writeStateData(_data) { }
+    async writeStateData(_data, _when) { }
     /**
      * No-op dispose.
      */
@@ -4196,18 +4198,19 @@ class PersistStateUtils {
          * Writes state for the given context.
          * Lazily initializes the instance on first access.
          *
-         * @param data - State data to persist
+         * @param data - State data to persist (already carries `data.when`)
          * @param signalId - Signal identifier
          * @param bucketName - Bucket name
+         * @param when - Logical timestamp this value belongs to (duplicates `data.when` for API consistency)
          * @returns Promise that resolves when write is complete
          */
-        this.writeStateData = async (data, signalId, bucketName) => {
+        this.writeStateData = async (data, signalId, bucketName, when) => {
             LOGGER_SERVICE$7.info(PERSIST_STATE_UTILS_METHOD_NAME_WRITE_DATA, { signalId, bucketName });
             const key = `${signalId}:${bucketName}`;
             const isInitial = !this.getStateStorage.has(key);
             const instance = this.getStateStorage(signalId, bucketName);
             await instance.waitForInit(isInitial);
-            return instance.writeStateData(data);
+            return instance.writeStateData(data, when);
         };
         /**
          * Switches to PersistStateDummyInstance (all operations are no-ops).
@@ -4317,7 +4320,7 @@ class PersistSessionInstance {
      * @param data - Session data to persist
      * @returns Promise that resolves when write is complete
      */
-    async writeSessionData(data) {
+    async writeSessionData(data, _when) {
         await this._storage.writeValue(this.frameName, data);
     }
     /**
@@ -4350,7 +4353,7 @@ class PersistSessionDummyInstance {
      * No-op write (discards session data).
      * @returns Promise that resolves immediately
      */
-    async writeSessionData(_data) { }
+    async writeSessionData(_data, _when) { }
     /**
      * No-op dispose.
      */
@@ -4418,19 +4421,20 @@ class PersistSessionUtils {
          * Writes session data for the given context.
          * Lazily initializes the instance on first access.
          *
-         * @param data - Session data to persist
+         * @param data - Session data to persist (already carries `data.when`)
          * @param strategyName - Strategy identifier
          * @param exchangeName - Exchange identifier
          * @param frameName - Frame identifier
+         * @param when - Logical timestamp this value belongs to (duplicates `data.when` for API consistency)
          * @returns Promise that resolves when write is complete
          */
-        this.writeSessionData = async (data, strategyName, exchangeName, frameName) => {
+        this.writeSessionData = async (data, strategyName, exchangeName, frameName, when) => {
             LOGGER_SERVICE$7.info(PERSIST_SESSION_UTILS_METHOD_NAME_WRITE_DATA, { strategyName, exchangeName, frameName });
             const key = `${strategyName}:${exchangeName}:${frameName}`;
             const isInitial = !this.getSessionStorage.has(key);
             const instance = this.getSessionStorage(strategyName, exchangeName, frameName);
             await instance.waitForInit(isInitial);
-            return instance.writeSessionData(data);
+            return instance.writeSessionData(data, when);
         };
         /**
          * Switches to PersistSessionDummyInstance (all operations are no-ops).
@@ -4609,8 +4613,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,
@@ -4641,7 +4645,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;
 };
 /**
@@ -4795,9 +4799,9 @@ const WRITE_CANDLES_CACHE_FN$1 = trycatch(queued(async (candles, dto, self) => {
  * @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
@@ -4911,11 +4915,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);
@@ -4992,11 +4996,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();
@@ -5181,11 +5185,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;
@@ -5314,7 +5318,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);
     }
     /**
@@ -5343,7 +5347,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);
@@ -6297,7 +6301,7 @@ const validateScheduledSignal = (signal, currentPrice) => {
     }
 };
 
-const INTERVAL_MINUTES$7 = {
+const INTERVAL_MINUTES$8 = {
     "1m": 1,
     "3m": 3,
     "5m": 5,
@@ -6718,7 +6722,7 @@ const GET_SIGNAL_FN = 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)
@@ -13713,7 +13717,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,
@@ -13767,7 +13771,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}`);
     }
@@ -14132,8 +14136,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,
@@ -14164,11 +14168,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);
 };
 
@@ -19650,8 +19654,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,
@@ -19666,7 +19670,7 @@ const INTERVAL_MINUTES$4 = {
 };
 const createEmitter = memoize(([interval]) => `${interval}`, (interval) => {
     const tickSubject = new 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;
         Source.fromInterval(EMITTER_CHECK_INTERVAL)
@@ -35172,7 +35176,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).
@@ -35239,7 +35243,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,
@@ -35270,7 +35274,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;
 };
 /**
@@ -35410,11 +35414,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();
@@ -35628,7 +35632,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);
         };
@@ -35660,7 +35664,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) {
@@ -35723,11 +35727,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);
@@ -36039,8 +36043,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,
@@ -36054,7 +36058,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;
@@ -36079,11 +36083,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 = join(baseDir, exchangeName, symbol, interval);
     const fromTs = ALIGN_TO_INTERVAL_FN(from.getTime(), step);
     const toTs = ALIGN_TO_INTERVAL_FN(to.getTime(), step);
@@ -36153,11 +36157,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);
@@ -48500,18 +48504,21 @@ class RecentPersistBacktestUtils {
             backtest.loggerService.info(RECENT_PERSIST_BACKTEST_METHOD_NAME_HANDLE_ACTIVE_PING, {
                 signalId: event.data.id,
             });
-            await PersistRecentAdapter.writeRecentData(event.data, event.symbol, event.strategyName, event.exchangeName, event.data.frameName, event.backtest);
+            await PersistRecentAdapter.writeRecentData(event.data, event.symbol, event.strategyName, event.exchangeName, event.data.frameName, event.backtest, new Date(event.data.timestamp));
         };
         /**
          * 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,
@@ -48519,20 +48526,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;
             }
@@ -48568,30 +48581,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;
             }
@@ -48619,18 +48641,21 @@ class RecentPersistLiveUtils {
             backtest.loggerService.info(RECENT_PERSIST_LIVE_METHOD_NAME_HANDLE_ACTIVE_PING, {
                 signalId: event.data.id,
             });
-            await PersistRecentAdapter.writeRecentData(event.data, event.symbol, event.strategyName, event.exchangeName, event.data.frameName, event.backtest);
+            await PersistRecentAdapter.writeRecentData(event.data, event.symbol, event.strategyName, event.exchangeName, event.data.frameName, event.backtest, new Date(event.data.timestamp));
         };
         /**
          * 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,
@@ -48638,20 +48663,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;
             }
@@ -48687,30 +48718,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;
             }
@@ -48750,9 +48790,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,
@@ -48760,18 +48801,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, {
@@ -48782,7 +48825,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;
             }
@@ -48854,9 +48897,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,
@@ -48864,18 +48908,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, {
@@ -48886,7 +48932,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;
             }
@@ -48976,14 +49022,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,
@@ -48992,10 +49040,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;
@@ -49003,13 +49051,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,
@@ -49018,13 +49069,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;
         };
@@ -49089,41 +49138,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 = 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 = queued(async (dispatch) => {
+        this.setState = 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. */
@@ -49157,14 +49219,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. */
@@ -49190,6 +49252,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
@@ -49204,40 +49267,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 = queued(async (dispatch) => {
+        this.setState = 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, when);
             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. */
@@ -49290,6 +49367,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) => {
@@ -49301,7 +49379,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.
@@ -49309,6 +49387,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) => {
@@ -49320,7 +49399,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).
@@ -49405,6 +49484,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) => {
@@ -49416,7 +49496,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.
@@ -49424,6 +49504,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) => {
@@ -49435,7 +49516,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.
@@ -49532,6 +49613,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
          */
@@ -49557,6 +49639,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
          */
@@ -49630,8 +49713,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.
@@ -49666,8 +49750,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.
@@ -49712,7 +49797,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;
@@ -49722,6 +49807,7 @@ async function getSignalState(symbol, dto) {
             bucketName,
             initialValue,
             backtest: isBacktest,
+            when,
         });
     }
     if (signal = await backtest.strategyCoreService.getScheduledSignal(isBacktest, symbol, currentPrice, { exchangeName, frameName, strategyName })) {
@@ -49730,6 +49816,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}`);
@@ -49781,7 +49868,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;
@@ -49791,6 +49878,7 @@ async function setSignalState(symbol, dispatch, dto) {
             bucketName,
             initialValue,
             backtest: isBacktest,
+            when,
         });
     }
     if (signal = await backtest.strategyCoreService.getScheduledSignal(isBacktest, symbol, currentPrice, { exchangeName, frameName, strategyName })) {
@@ -49799,6 +49887,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}`);
@@ -49852,36 +49941,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 = 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. */
@@ -49917,13 +50017,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. */
@@ -49949,6 +50049,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
@@ -49964,35 +50065,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, when);
         };
     }
     /** Releases resources held by this instance. */
@@ -50025,9 +50138,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,
@@ -50037,7 +50151,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.
@@ -50046,8 +50160,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,
@@ -50057,7 +50172,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).
@@ -50121,9 +50236,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,
@@ -50133,7 +50249,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.
@@ -50142,8 +50258,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,
@@ -50153,7 +50270,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.
@@ -50213,9 +50330,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,
@@ -50223,9 +50341,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.
@@ -50236,8 +50354,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,
@@ -50245,9 +50364,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);
         };
     }
 }
@@ -50299,9 +50418,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.
@@ -50333,9 +50452,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";
@@ -50346,7 +50465,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;
@@ -50356,6 +50475,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 })) {
@@ -50364,6 +50484,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}`);
@@ -50375,7 +50496,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;
@@ -50385,6 +50506,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 })) {
@@ -50393,6 +50515,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}`);
@@ -50475,7 +50598,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);
@@ -50484,12 +50607,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);
@@ -50497,16 +50629,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) {
@@ -50603,8 +50749,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,
@@ -50615,21 +50762,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}`);
         }
@@ -50637,33 +50787,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,
@@ -50709,12 +50864,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,
             });
         }
     }
@@ -50723,69 +50879,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, when);
         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,
@@ -50822,34 +50988,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() {
@@ -50893,6 +51059,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, {
@@ -50904,13 +51071,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) => {
@@ -50923,12 +51091,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) => {
@@ -50940,13 +51109,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, {
@@ -50958,13 +51128,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
          */
@@ -50978,7 +51149,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).
@@ -51060,6 +51231,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, {
@@ -51071,13 +51243,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) => {
@@ -51090,12 +51263,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) => {
@@ -51107,13 +51281,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, {
@@ -51125,13 +51300,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
          */
@@ -51145,7 +51321,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.
@@ -51244,6 +51420,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()) {
@@ -51267,6 +51444,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) => {
@@ -51290,6 +51468,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) => {
@@ -51313,6 +51492,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()) {
@@ -51336,6 +51516,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
          */
@@ -51408,7 +51589,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;
@@ -51420,6 +51601,7 @@ async function writeMemory(dto) {
             bucketName,
             description,
             backtest: isBacktest,
+            when,
         });
         return;
     }
@@ -51431,6 +51613,7 @@ async function writeMemory(dto) {
             bucketName,
             description,
             backtest: isBacktest,
+            when,
         });
         return;
     }
@@ -51466,7 +51649,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;
@@ -51476,6 +51659,7 @@ async function readMemory(dto) {
             signalId: signal.id,
             bucketName,
             backtest: isBacktest,
+            when,
         });
     }
     if (signal = await backtest.strategyCoreService.getScheduledSignal(isBacktest, symbol, currentPrice, { exchangeName, frameName, strategyName })) {
@@ -51484,6 +51668,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}`);
@@ -51518,7 +51703,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;
@@ -51528,6 +51713,7 @@ async function searchMemory(dto) {
             signalId: signal.id,
             bucketName,
             backtest: isBacktest,
+            when,
         });
     }
     if (signal = await backtest.strategyCoreService.getScheduledSignal(isBacktest, symbol, currentPrice, { exchangeName, frameName, strategyName })) {
@@ -51536,6 +51722,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}`);
@@ -51568,7 +51755,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;
@@ -51577,6 +51764,7 @@ async function listMemory(dto) {
             signalId: signal.id,
             bucketName,
             backtest: isBacktest,
+            when,
         });
     }
     if (signal = await backtest.strategyCoreService.getScheduledSignal(isBacktest, symbol, currentPrice, { exchangeName, frameName, strategyName })) {
@@ -51584,6 +51772,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}`);
@@ -51618,7 +51807,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;
@@ -51628,6 +51817,7 @@ async function removeMemory(dto) {
             signalId: signal.id,
             bucketName,
             backtest: isBacktest,
+            when,
         });
         return;
     }
@@ -51637,6 +51827,7 @@ async function removeMemory(dto) {
             signalId: signal.id,
             bucketName,
             backtest: isBacktest,
+            when,
         });
         return;
     }
@@ -51902,6 +52093,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)
         });
     }
     /**
@@ -51924,6 +52118,7 @@ class DumpMemoryInstance {
             value: record,
             description,
             backtest: this.backtest,
+            when: new Date(0)
         });
     }
     /**
@@ -51947,6 +52142,7 @@ class DumpMemoryInstance {
             value: { rows },
             description,
             backtest: this.backtest,
+            when: new Date(0)
         });
     }
     /**
@@ -51969,6 +52165,7 @@ class DumpMemoryInstance {
             value: { content },
             description,
             backtest: this.backtest,
+            when: new Date(0)
         });
     }
     /**
@@ -51991,6 +52188,7 @@ class DumpMemoryInstance {
             value: { content },
             description,
             backtest: this.backtest,
+            when: new Date(0)
         });
     }
     /**
@@ -52014,6 +52212,7 @@ class DumpMemoryInstance {
             value: json,
             description,
             backtest: this.backtest,
+            when: new Date(0)
         });
     }
     /** Releases resources held by this instance. */
@@ -60975,8 +61174,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,
@@ -61010,11 +61209,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;
 };
 /**
@@ -61103,7 +61302,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");
@@ -61298,7 +61497,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");
@@ -61320,7 +61519,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;
         };
         /**
@@ -61609,8 +61808,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,
@@ -61640,11 +61839,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;
 };
 /**
@@ -61719,7 +61918,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");
@@ -61886,7 +62085,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");
@@ -61909,7 +62108,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;
         };
@@ -63033,6 +63232,31 @@ class ActionBase {
 // @ts-ignore
 ActionBase = 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.
  *
@@ -63299,4 +63523,4 @@ const validateSignal = (signal, currentPrice) => {
     return !errors.length;
 };
 
-export { ActionBase, Backtest, Breakeven, Broker, BrokerBase, Cache, Constant, Dump, Exchange, ExecutionContextService, Heat, HighestProfit, Interval, Live, Log, Markdown, MarkdownFileBase, MarkdownFolderBase, MarkdownWriter, MaxDrawdown, Memory, MemoryBacktest, MemoryBacktestAdapter, MemoryLive, MemoryLiveAdapter, MethodContextService, Notification, NotificationBacktest, NotificationLive, Partial, Performance, PersistBase, PersistBreakevenAdapter, PersistBreakevenInstance, PersistCandleAdapter, PersistCandleInstance, PersistIntervalAdapter, PersistIntervalInstance, PersistLogAdapter, PersistLogInstance, PersistMeasureAdapter, PersistMeasureInstance, PersistMemoryAdapter, PersistMemoryInstance, PersistNotificationAdapter, PersistNotificationInstance, PersistPartialAdapter, PersistPartialInstance, PersistRecentAdapter, PersistRecentInstance, PersistRiskAdapter, PersistRiskInstance, PersistScheduleAdapter, PersistScheduleInstance, PersistSessionAdapter, PersistSessionInstance, PersistSignalAdapter, PersistSignalInstance, PersistStateAdapter, PersistStateInstance, PersistStorageAdapter, PersistStorageInstance, Position, PositionSize, Recent, RecentBacktest, RecentLive, Reflect$1 as Reflect, Report, ReportBase, ReportWriter, Risk, Schedule, Session, SessionBacktest, SessionLive, State, StateBacktest, StateBacktestAdapter, StateLive, StateLiveAdapter, Storage, StorageBacktest, StorageLive, Strategy, Sync, System, Walker, addActionSchema, addExchangeSchema, addFrameSchema, addRiskSchema, addSizingSchema, addStrategySchema, addWalkerSchema, alignToInterval, checkCandles, commitActivateScheduled, commitAverageBuy, commitBreakeven, commitCancelScheduled, commitClosePending, commitPartialLoss, commitPartialLossCost, commitPartialProfit, commitPartialProfitCost, commitSignalNotify, commitTrailingStop, commitTrailingStopCost, commitTrailingTake, commitTrailingTakeCost, createSignalState, dumpAgentAnswer, dumpError, dumpJson, dumpRecord, dumpTable, dumpText, emitters, formatPrice, formatQuantity, get, getActionSchema, getAggregatedTrades, getAveragePrice, getBacktestTimeframe, getBreakeven, getCandles, getClosePrice, getColumns, getConfig, getContext, getDate, getDefaultColumns, getDefaultConfig, getEffectivePriceOpen, getExchangeSchema, getFrameSchema, getLatestSignal, getMaxDrawdownDistancePnlCost, getMaxDrawdownDistancePnlPercentage, getMinutesSinceLatestSignalCreated, getMode, getNextCandles, getOrderBook, getPendingSignal, getPositionActiveMinutes, getPositionCountdownMinutes, getPositionDrawdownMinutes, getPositionEffectivePrice, getPositionEntries, getPositionEntryOverlap, getPositionEstimateMinutes, getPositionHighestMaxDrawdownPnlCost, getPositionHighestMaxDrawdownPnlPercentage, getPositionHighestPnlCost, getPositionHighestPnlPercentage, getPositionHighestProfitBreakeven, getPositionHighestProfitDistancePnlCost, getPositionHighestProfitDistancePnlPercentage, getPositionHighestProfitMinutes, getPositionHighestProfitPrice, getPositionHighestProfitTimestamp, getPositionInvestedCost, getPositionInvestedCount, getPositionLevels, getPositionMaxDrawdownMinutes, getPositionMaxDrawdownPnlCost, getPositionMaxDrawdownPnlPercentage, getPositionMaxDrawdownPrice, getPositionMaxDrawdownTimestamp, getPositionPartialOverlap, getPositionPartials, getPositionPnlCost, getPositionPnlPercent, getPositionWaitingMinutes, getRawCandles, getRiskSchema, getScheduledSignal, getSessionData, getSignalState, getSizingSchema, getStrategySchema, getSymbol, getTimestamp, getTotalClosed, getTotalCostClosed, getTotalPercentClosed, getWalkerSchema, hasNoPendingSignal, hasNoScheduledSignal, hasTradeContext, investedCostToPercent, backtest as lib, listExchangeSchema, listFrameSchema, listMemory, listRiskSchema, listSizingSchema, listStrategySchema, listWalkerSchema, listenActivePing, listenActivePingOnce, listenBacktestProgress, listenBreakevenAvailable, listenBreakevenAvailableOnce, listenDoneBacktest, listenDoneBacktestOnce, listenDoneLive, listenDoneLiveOnce, listenDoneWalker, listenDoneWalkerOnce, listenError, listenExit, listenHighestProfit, listenHighestProfitOnce, listenIdlePing, listenIdlePingOnce, listenMaxDrawdown, listenMaxDrawdownOnce, listenPartialLossAvailable, listenPartialLossAvailableOnce, listenPartialProfitAvailable, listenPartialProfitAvailableOnce, listenPerformance, listenRisk, listenRiskOnce, listenSchedulePing, listenSchedulePingOnce, listenSignal, listenSignalBacktest, listenSignalBacktestOnce, listenSignalLive, listenSignalLiveOnce, listenSignalNotify, listenSignalNotifyOnce, listenSignalOnce, listenStrategyCommit, listenStrategyCommitOnce, listenSync, listenSyncOnce, listenValidation, listenWalker, listenWalkerComplete, listenWalkerOnce, listenWalkerProgress, overrideActionSchema, overrideExchangeSchema, overrideFrameSchema, overrideRiskSchema, overrideSizingSchema, overrideStrategySchema, overrideWalkerSchema, parseArgs, percentDiff, percentToCloseCost, percentValue, readMemory, removeMemory, roundTicks, runInMockContext, searchMemory, set, setColumns, setConfig, setLogger, setSessionData, setSignalState, shutdown, slPercentShiftToPrice, slPriceToPercentShift, stopStrategy, toProfitLossDto, tpPercentShiftToPrice, tpPriceToPercentShift, validate, validateCommonSignal, validatePendingSignal, validateScheduledSignal, validateSignal, waitForCandle, warmCandles, writeMemory };
+export { ActionBase, Backtest, Breakeven, Broker, BrokerBase, Cache, Constant, Dump, Exchange, ExecutionContextService, Heat, HighestProfit, Interval, Live, Log, Markdown, MarkdownFileBase, MarkdownFolderBase, MarkdownWriter, MaxDrawdown, Memory, MemoryBacktest, MemoryBacktestAdapter, MemoryLive, MemoryLiveAdapter, MethodContextService, Notification, NotificationBacktest, NotificationLive, Partial, Performance, PersistBase, PersistBreakevenAdapter, PersistBreakevenInstance, PersistCandleAdapter, PersistCandleInstance, PersistIntervalAdapter, PersistIntervalInstance, PersistLogAdapter, PersistLogInstance, PersistMeasureAdapter, PersistMeasureInstance, PersistMemoryAdapter, PersistMemoryInstance, PersistNotificationAdapter, PersistNotificationInstance, PersistPartialAdapter, PersistPartialInstance, PersistRecentAdapter, PersistRecentInstance, PersistRiskAdapter, PersistRiskInstance, PersistScheduleAdapter, PersistScheduleInstance, PersistSessionAdapter, PersistSessionInstance, PersistSignalAdapter, PersistSignalInstance, PersistStateAdapter, PersistStateInstance, PersistStorageAdapter, PersistStorageInstance, Position, PositionSize, Recent, RecentBacktest, RecentLive, Reflect$1 as Reflect, Report, ReportBase, ReportWriter, Risk, Schedule, Session, SessionBacktest, SessionLive, State, StateBacktest, StateBacktestAdapter, StateLive, StateLiveAdapter, Storage, StorageBacktest, StorageLive, Strategy, Sync, System, Walker, addActionSchema, addExchangeSchema, addFrameSchema, addRiskSchema, addSizingSchema, addStrategySchema, addWalkerSchema, alignToInterval, checkCandles, commitActivateScheduled, commitAverageBuy, commitBreakeven, commitCancelScheduled, commitClosePending, commitPartialLoss, commitPartialLossCost, commitPartialProfit, commitPartialProfitCost, commitSignalNotify, commitTrailingStop, commitTrailingStopCost, commitTrailingTake, commitTrailingTakeCost, createSignalState, dumpAgentAnswer, dumpError, dumpJson, dumpRecord, dumpTable, dumpText, emitters, formatPrice, formatQuantity, get, getActionSchema, getAggregatedTrades, getAveragePrice, getBacktestTimeframe, getBreakeven, getCandles, getClosePrice, getColumns, getConfig, getContext, getDate, getDefaultColumns, getDefaultConfig, getEffectivePriceOpen, getExchangeSchema, getFrameSchema, getLatestSignal, getMaxDrawdownDistancePnlCost, getMaxDrawdownDistancePnlPercentage, getMinutesSinceLatestSignalCreated, getMode, getNextCandles, getOrderBook, getPendingSignal, getPositionActiveMinutes, getPositionCountdownMinutes, getPositionDrawdownMinutes, getPositionEffectivePrice, getPositionEntries, getPositionEntryOverlap, getPositionEstimateMinutes, getPositionHighestMaxDrawdownPnlCost, getPositionHighestMaxDrawdownPnlPercentage, getPositionHighestPnlCost, getPositionHighestPnlPercentage, getPositionHighestProfitBreakeven, getPositionHighestProfitDistancePnlCost, getPositionHighestProfitDistancePnlPercentage, getPositionHighestProfitMinutes, getPositionHighestProfitPrice, getPositionHighestProfitTimestamp, getPositionInvestedCost, getPositionInvestedCount, getPositionLevels, getPositionMaxDrawdownMinutes, getPositionMaxDrawdownPnlCost, getPositionMaxDrawdownPnlPercentage, getPositionMaxDrawdownPrice, getPositionMaxDrawdownTimestamp, getPositionPartialOverlap, getPositionPartials, getPositionPnlCost, getPositionPnlPercent, getPositionWaitingMinutes, getRawCandles, getRiskSchema, getScheduledSignal, getSessionData, getSignalState, getSizingSchema, getStrategySchema, getSymbol, getTimestamp, getTotalClosed, getTotalCostClosed, getTotalPercentClosed, getWalkerSchema, hasNoPendingSignal, hasNoScheduledSignal, hasTradeContext, intervalStepMs, investedCostToPercent, backtest as lib, listExchangeSchema, listFrameSchema, listMemory, listRiskSchema, listSizingSchema, listStrategySchema, listWalkerSchema, listenActivePing, listenActivePingOnce, listenBacktestProgress, listenBreakevenAvailable, listenBreakevenAvailableOnce, listenDoneBacktest, listenDoneBacktestOnce, listenDoneLive, listenDoneLiveOnce, listenDoneWalker, listenDoneWalkerOnce, listenError, listenExit, listenHighestProfit, listenHighestProfitOnce, listenIdlePing, listenIdlePingOnce, listenMaxDrawdown, listenMaxDrawdownOnce, listenPartialLossAvailable, listenPartialLossAvailableOnce, listenPartialProfitAvailable, listenPartialProfitAvailableOnce, listenPerformance, listenRisk, listenRiskOnce, listenSchedulePing, listenSchedulePingOnce, listenSignal, listenSignalBacktest, listenSignalBacktestOnce, listenSignalLive, listenSignalLiveOnce, listenSignalNotify, listenSignalNotifyOnce, listenSignalOnce, listenStrategyCommit, listenStrategyCommitOnce, listenSync, listenSyncOnce, listenValidation, listenWalker, listenWalkerComplete, listenWalkerOnce, listenWalkerProgress, overrideActionSchema, overrideExchangeSchema, overrideFrameSchema, overrideRiskSchema, overrideSizingSchema, overrideStrategySchema, overrideWalkerSchema, parseArgs, percentDiff, percentToCloseCost, percentValue, readMemory, removeMemory, roundTicks, runInMockContext, searchMemory, set, setColumns, setConfig, setLogger, setSessionData, setSignalState, shutdown, slPercentShiftToPrice, slPriceToPercentShift, stopStrategy, toProfitLossDto, tpPercentShiftToPrice, tpPriceToPercentShift, validate, validateCommonSignal, validatePendingSignal, validateScheduledSignal, validateSignal, waitForCandle, warmCandles, writeMemory };