backtest-kit 11.6.0 → 11.8.0

package/build/index.mjs

@@ -74,6 +74,7 @@ const metaServices$1 = {
     contextMetaService: Symbol('contextMetaService'),
     priceMetaService: Symbol('priceMetaService'),
     timeMetaService: Symbol('timeMetaService'),
+    runtimeMetaService: Symbol('runtimeMetaService'),
 };
 const globalServices$1 = {
     sizingGlobalService: Symbol('sizingGlobalService'),
@@ -12356,6 +12357,7 @@ const CREATE_COMMIT_SCHEDULE_PING_FN = (self) => trycatch(async (symbol, strateg
         symbol,
         strategyName,
         exchangeName,
+        frameName: data.frameName,
         currentPrice,
         data,
         backtest,
@@ -12423,6 +12425,7 @@ const CREATE_COMMIT_ACTIVE_PING_FN = (self) => trycatch(async (symbol, strategyN
         symbol,
         strategyName,
         exchangeName,
+        frameName: data.frameName,
         currentPrice,
         data,
         backtest,
@@ -13995,11 +13998,51 @@ class StrategyConnectionService {
     }
 }
 
+const MS_PER_MINUTE$6 = 60000;
+const INTERVAL_MINUTES$7 = {
+    "1m": 1,
+    "3m": 3,
+    "5m": 5,
+    "15m": 15,
+    "30m": 30,
+    "1h": 60,
+    "2h": 120,
+    "4h": 240,
+    "6h": 360,
+    "8h": 480,
+    "1d": 1440,
+};
+/**
+ * Aligns timestamp down to the nearest interval boundary.
+ * For example, for 15m interval: 00:17 -> 00:15, 00:44 -> 00:30
+ *
+ * Candle timestamp convention:
+ * - Candle timestamp = openTime (when candle opens)
+ * - Candle with timestamp 00:00 covers period [00:00, 00:15) for 15m interval
+ *
+ * Adapter contract:
+ * - Adapter must return candles with timestamp = openTime
+ * - First returned candle.timestamp must equal aligned since
+ * - Adapter must return exactly `limit` candles
+ *
+ * @param date - Date to align
+ * @param interval - Candle interval (e.g., "1m", "15m", "1h")
+ * @returns New Date aligned down to interval boundary
+ */
+const alignToInterval = (date, interval) => {
+    const minutes = INTERVAL_MINUTES$7[interval];
+    if (minutes === undefined) {
+        throw new Error(`alignToInterval: unknown interval=${interval}`);
+    }
+    const intervalMs = minutes * MS_PER_MINUTE$6;
+    return new Date(Math.floor(date.getTime() / intervalMs) * intervalMs);
+};
+
 /**
  * Maps FrameInterval to minutes for timestamp calculation.
  * Used to generate timeframe arrays with proper spacing.
  */
-const INTERVAL_MINUTES$7 = {
+const INTERVAL_MINUTES$6 = {
     "1m": 1,
     "3m": 3,
     "5m": 5,
@@ -14053,7 +14096,7 @@ const GET_TIMEFRAME_FN = async (symbol, self) => {
         symbol,
     });
     const { interval, startDate, endDate } = self.params;
-    const intervalMinutes = INTERVAL_MINUTES$7[interval];
+    const intervalMinutes = INTERVAL_MINUTES$6[interval];
     if (!intervalMinutes) {
         throw new Error(`ClientFrame unknown interval: ${interval}`);
     }
@@ -14062,8 +14105,14 @@ const GET_TIMEFRAME_FN = async (symbol, self) => {
     today.setUTCHours(0, 0, 0, 0);
     // Ensure endDate doesn't go beyond today
     const effectiveEndDate = endDate > today ? today : endDate;
+    // Align the iteration start down to the 1-minute boundary so every generated
+    // timestamp lands on a clean minute, matching live mode
+    // (LiveLogicPrivateService aligns `when` via alignToInterval(new Date(), "1m")).
+    // Without this, a startDate carrying sub-minute (or any non-aligned) offset
+    // would propagate that offset to every tick `when` — and therefore to
+    // IRuntimeInfo.when handed to Cron handlers — diverging from live behaviour.
     const timeframes = [];
-    let currentDate = new Date(startDate);
+    let currentDate = alignToInterval(startDate, "1m");
     while (currentDate <= effectiveEndDate) {
         timeframes.push(new Date(currentDate));
         currentDate = new Date(currentDate.getTime() + intervalMinutes * 60 * 1000);
@@ -19914,8 +19963,8 @@ class BacktestLogicPrivateService {
 }
 
 const EMITTER_CHECK_INTERVAL = 5000;
-const MS_PER_MINUTE$6 = 60000;
-const INTERVAL_MINUTES$6 = {
+const MS_PER_MINUTE$5 = 60000;
+const INTERVAL_MINUTES$5 = {
     "1m": 1,
     "3m": 3,
     "5m": 5,
@@ -19930,7 +19979,7 @@ const INTERVAL_MINUTES$6 = {
 };
 const createEmitter = memoize(([interval]) => `${interval}`, (interval) => {
     const tickSubject = new Subject();
-    const intervalMs = INTERVAL_MINUTES$6[interval] * MS_PER_MINUTE$6;
+    const intervalMs = INTERVAL_MINUTES$5[interval] * MS_PER_MINUTE$5;
     {
         let lastAligned = Math.floor(Date.now() / intervalMs) * intervalMs;
         Source.fromInterval(EMITTER_CHECK_INTERVAL)
@@ -19957,46 +20006,6 @@ const waitForCandle = async (interval) => {
     return emitter.toPromise();
 };
 
-const MS_PER_MINUTE$5 = 60000;
-const INTERVAL_MINUTES$5 = {
-    "1m": 1,
-    "3m": 3,
-    "5m": 5,
-    "15m": 15,
-    "30m": 30,
-    "1h": 60,
-    "2h": 120,
-    "4h": 240,
-    "6h": 360,
-    "8h": 480,
-    "1d": 1440,
-};
-/**
- * Aligns timestamp down to the nearest interval boundary.
- * For example, for 15m interval: 00:17 -> 00:15, 00:44 -> 00:30
- *
- * Candle timestamp convention:
- * - Candle timestamp = openTime (when candle opens)
- * - Candle with timestamp 00:00 covers period [00:00, 00:15) for 15m interval
- *
- * Adapter contract:
- * - Adapter must return candles with timestamp = openTime
- * - First returned candle.timestamp must equal aligned since
- * - Adapter must return exactly `limit` candles
- *
- * @param date - Date to align
- * @param interval - Candle interval (e.g., "1m", "15m", "1h")
- * @returns New Date aligned down to interval boundary
- */
-const alignToInterval = (date, interval) => {
-    const minutes = INTERVAL_MINUTES$5[interval];
-    if (minutes === undefined) {
-        throw new Error(`alignToInterval: unknown interval=${interval}`);
-    }
-    const intervalMs = minutes * MS_PER_MINUTE$5;
-    return new Date(Math.floor(date.getTime() / intervalMs) * intervalMs);
-};
-
 /**
  * Private service for live trading orchestration using async generators.
  *
@@ -23958,13 +23967,19 @@ let ReportStorage$a = class ReportStorage {
         // mark-to-market low); equity then moves to the realized close.
         // If equity (at trough or close) goes ≤ 0 (e.g. leveraged loss < -100%) — account
         // blown, fix DD at 100% and stop walking the curve.
+        // Walk the equity curve in chronological close order. Storage is
+        // newest-first (unshift on addSignal); reverse-storage iteration normally
+        // gives chronological order, but explicitly sorting by closeTimestamp
+        // removes the dependency on insertion-order matching close-order (which
+        // can break under crash recovery, signal backfill, or disk replays).
+        const orderedSignals = [...validSignals].sort((a, b) => a.closeTimestamp - b.closeTimestamp);
         let equity = 1;
         let peak = 1;
         let equityMaxDrawdown = 0;
         let blown = false;
-        for (let i = validSignals.length - 1; i >= 0; i--) {
+        for (const s of orderedSignals) {
             // Intra-trade trough — mark-to-market low while the position was open.
-            const fallPct = validSignals[i].signal.maxDrawdown?.pnlPercentage;
+            const fallPct = s.signal.maxDrawdown?.pnlPercentage;
             if (typeof fallPct === "number" && fallPct < 0) {
                 const trough = equity * (1 + fallPct / 100);
                 if (trough <= 0) {
@@ -23977,7 +23992,7 @@ let ReportStorage$a = class ReportStorage {
                     equityMaxDrawdown = troughDd;
             }
             // Realized close — book the final per-trade result.
-            equity *= 1 + validSignals[i].pnl.pnlPercentage / 100;
+            equity *= 1 + s.pnl.pnlPercentage / 100;
             if (equity <= 0) {
                 equityMaxDrawdown = 100;
                 blown = true;
@@ -25122,14 +25137,20 @@ let ReportStorage$9 = class ReportStorage {
         // snapshot, ≤ 0) is applied as a trough BEFORE booking the realized close. Without it
         // the curve only steps at close, so a trade that dipped to -18% and recovered to +2%
         // would register zero drawdown — understating DD and inflating Calmar/Recovery.
-        const chronological = [];
-        for (let i = validClosed.length - 1; i >= 0; i--) {
-            const fall = validClosed[i].fallPnl;
-            chronological.push({
-                r: validClosed[i].pnl,
-                fall: typeof fall === "number" ? fall : null,
-            });
-        }
+        // Walk the equity curve in chronological close order. Reverse-storage
+        // iteration (newest-first storage → reverse) normally yields chronological
+        // order for live ingest, but explicitly sorting by event.timestamp removes
+        // the dependency on insertion-order matching close-order. This matters
+        // under crash recovery (events reloaded from disk in arbitrary order) and
+        // when ingest latency reorders closed events relative to wall-clock time.
+        const chronological = validClosed
+            .map((e) => ({
+            r: e.pnl,
+            fall: typeof e.fallPnl === "number" ? e.fallPnl : null,
+            ts: e.timestamp,
+        }))
+            .sort((a, b) => a.ts - b.ts)
+            .map(({ r, fall }) => ({ r, fall }));
         let equity = 1;
         let peak = 1;
         let equityMaxDrawdown = 0;
@@ -27203,11 +27224,18 @@ class HeatmapStorage {
         let equityFinal = 1;
         let blown = false;
         if (signals.length > 0) {
+            // Walk the per-symbol equity curve in chronological close order.
+            // Storage is newest-first (unshift on addSignal), but if signals were
+            // ingested out-of-order (e.g. Live + crash recovery loading from disk in
+            // arbitrary order, or a backfill replay), reverse-storage iteration
+            // would misplace peak/trough and silently distort maxDrawdown. Sorting
+            // by closeTimestamp explicitly removes that dependency.
+            const ordered = [...signals].sort((a, b) => a.closeTimestamp - b.closeTimestamp);
             let equity = 1;
             let peak = 1;
             let maxDD = 0;
-            for (let i = signals.length - 1; i >= 0; i--) {
-                const fallPct = signals[i].signal.maxDrawdown?.pnlPercentage;
+            for (const s of ordered) {
+                const fallPct = s.signal.maxDrawdown?.pnlPercentage;
                 if (typeof fallPct === "number" && fallPct < 0) {
                     const trough = equity * (1 + fallPct / 100);
                     if (trough <= 0) {
@@ -27219,7 +27247,7 @@ class HeatmapStorage {
                     if (troughDd > maxDD)
                         maxDD = troughDd;
                 }
-                equity *= 1 + signals[i].pnl.pnlPercentage / 100;
+                equity *= 1 + s.pnl.pnlPercentage / 100;
                 if (equity <= 0) {
                     maxDD = 100;
                     blown = true;
@@ -27656,23 +27684,28 @@ class HeatmapStorage {
         let portfolioCertaintyRatio = null;
         let portfolioExpectedYearlyReturns = null;
         let portfolioTradesPerYear = null;
-        const allReturns = [];
-        // Parallel array of intra-trade troughs (≤ 0), aligned 1:1 with allReturns,
-        // used for mark-to-market DD in the pooled equity curve below.
-        const allFalls = [];
+        const pooledTrades = [];
         let poolFirstPendingAt = Infinity;
         let poolLastCloseAt = -Infinity;
         for (const signals of this.symbolData.values()) {
             for (const s of signals) {
-                allReturns.push(s.pnl.pnlPercentage);
                 const fall = s.signal.maxDrawdown?.pnlPercentage;
-                allFalls.push(typeof fall === "number" ? fall : null);
+                pooledTrades.push({
+                    r: s.pnl.pnlPercentage,
+                    fall: typeof fall === "number" ? fall : null,
+                    closeAt: s.closeTimestamp,
+                });
                 if (s.signal.pendingAt < poolFirstPendingAt)
                     poolFirstPendingAt = s.signal.pendingAt;
                 if (s.closeTimestamp > poolLastCloseAt)
                     poolLastCloseAt = s.closeTimestamp;
             }
         }
+        pooledTrades.sort((a, b) => a.closeAt - b.closeAt);
+        const allReturns = pooledTrades.map((t) => t.r);
+        // Parallel array of intra-trade troughs (≤ 0), aligned 1:1 with allReturns,
+        // used for mark-to-market DD in the pooled equity curve below.
+        const allFalls = pooledTrades.map((t) => t.fall);
         if (allReturns.length >= MIN_SIGNALS_FOR_RATIOS) {
             const portfolioAvg = allReturns.reduce((acc, r) => acc + r, 0) / allReturns.length;
             const portfolioVariance = allReturns.reduce((acc, r) => acc + Math.pow(r - portfolioAvg, 2), 0) /
@@ -28046,7 +28079,7 @@ class HeatmapStorage {
             `*Peak Profit PNL / Max Drawdown PNL: extremes — the best best-case and worst worst-case observed across all trades. Tail behaviour the averages hide.*`,
             `*Avg Duration / Avg Win Duration / Avg Loss Duration: mean hold time in minutes (closeTimestamp - pendingAt). Winner-shorter-than-loser is a red flag ("cut winners short, let losers run").*`,
             `*Avg Consecutive Win/Loss PNL: average sum of pnlPercentage across consecutive streaks. Pairs with max streak length to show the typical (not worst-case) streak magnitude. Portfolio uses trade-count-weighted mean of per-symbol streak averages — concatenating streaks across symbols would be meaningless (different markets, different timeframes).*`,
-            `*Max Drawdown: mark-to-market — both the per-symbol and pooled equity curves apply each trade's worst intra-trade excursion (the lowest unrealized point while the position was open) before booking its realized close, so deep round-trip dips count. It is NOT realized-only (close-to-close); a realized-only curve would understate drawdown and inflate Calmar/Recovery. NOTE: the pooled curve orders trades by storage sequence, not wall-clock time, so simultaneous cross-symbol drawdowns are not modelled.*`,
+            `*Max Drawdown: mark-to-market — both the per-symbol and pooled equity curves apply each trade's worst intra-trade excursion (the lowest unrealized point while the position was open) before booking its realized close, so deep round-trip dips count. It is NOT realized-only (close-to-close); a realized-only curve would understate drawdown and inflate Calmar/Recovery. The pooled curve walks trades chronologically by closeTimestamp; simultaneous cross-symbol drawdowns within the same minute are still serialised (one trade applied at a time), so genuine same-instant tail correlation is not modelled.*`,
             `*All metrics require 100+ signals per symbol to be statistically reliable. Annualized metrics assume the observed trading frequency persists year-round.*`,
             `*IMPORTANT: Per-symbol equity curve, Expected Yearly Returns, Calmar, Recovery and Max Drawdown all assume **100% capital allocation per position** (no portfolio fraction). These metrics ignore the position-sizing subsystem (PositionSize / Kelly / ATR): pnlPercentage is a return on the position's own invested capital, never scaled by account balance. With DCA (commitAverageBuy) the cost basis is the sum of all entries and the entry price is dollar-cost-weighted, so per-trade % is measured against the averaged position, not a fixed stake. If your strategy risks X% of capital per trade, the realized return / drawdown will be roughly X/100 of the reported figures — these metrics represent a theoretical upper bound under full allocation.*`,
             `*Negative values for Sharpe / Annualized Sharpe / Sortino / Calmar / Recovery / Expectancy / Expected Yearly Returns indicate a losing symbol (avgPnl < 0 or totalPnl < 0). "Higher is better" still applies — closer to zero is less bad, positive is profitable.*`,
@@ -36111,6 +36144,21 @@ class PriceMetaService {
          * Instances are cached until clear() is called.
          */
         this.getSource = memoize(([symbol, strategyName, exchangeName, frameName, backtest]) => CREATE_KEY_FN$b(symbol, strategyName, exchangeName, frameName, backtest), () => new BehaviorSubject());
+        /**
+         * Checks if a price exists for the given key and has emitted at least one value.
+         *
+         * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+         * @param context - Strategy, exchange, and frame identifiers
+         * @param backtest - True if backtest mode, false if live mode
+         * @returns True if a price exists and has emitted a value, false otherwise
+         */
+        this.hasPrice = (symbol, context, backtest) => {
+            const key = CREATE_KEY_FN$b(symbol, context.strategyName, context.exchangeName, context.frameName, backtest);
+            if (!this.getSource.has(key)) {
+                return false;
+            }
+            return !!this.getSource.get(key)?.data;
+        };
         /**
          * Returns the current market price for the given symbol and context.
          *
@@ -36773,6 +36821,129 @@ class NotificationHelperService {
     }
 }
 
+const GET_RANGE_FN = trycatch((self, context, backtest) => {
+    if (!backtest) {
+        return null;
+    }
+    const { startDate, endDate } = self.frameSchemaService.get(context.frameName);
+    return {
+        from: startDate,
+        to: endDate,
+    };
+}, {
+    fallback: (error, self) => {
+        const message = "RuntimeMetaService GET_RANGE_FN thrown";
+        const payload = {
+            error: errorData(error),
+            message: getErrorMessage(error),
+        };
+        self.loggerService.warn(message, payload);
+        console.error(message, payload);
+        errorEmitter.next(error);
+    },
+    defaultValue: null,
+});
+const GET_INFO_FN = trycatch((self, context) => {
+    const { info } = self.strategySchemaService.get(context.strategyName);
+    return info || null;
+}, {
+    fallback: (error, self) => {
+        const message = "RuntimeMetaService GET_INFO_FN thrown";
+        const payload = {
+            error: errorData(error),
+            message: getErrorMessage(error),
+        };
+        self.loggerService.warn(message, payload);
+        console.error(message, payload);
+        errorEmitter.next(error);
+    },
+    defaultValue: null,
+});
+const GET_PRICE_FN = trycatch(async (self, symbol, context, backtest) => {
+    return await self.priceMetaService.getCurrentPrice(symbol, context, backtest);
+}, {
+    fallback: (error, self) => {
+        const message = "RuntimeMetaService GET_PRICE_FN thrown";
+        const payload = {
+            error: errorData(error),
+            message: getErrorMessage(error),
+        };
+        self.loggerService.warn(message, payload);
+        console.error(message, payload);
+        errorEmitter.next(error);
+    },
+    defaultValue: null,
+});
+const RuntimeMetaService = singleton(class {
+    constructor() {
+        this.loggerService = inject(TYPES.loggerService);
+        this.timeMetaService = inject(TYPES.timeMetaService);
+        this.priceMetaService = inject(TYPES.priceMetaService);
+        this.frameSchemaService = inject(TYPES.frameSchemaService);
+        this.strategySchemaService = inject(TYPES.strategySchemaService);
+        /**
+         * Fetches the time range for the current strategy execution context.
+         *
+         * For backtest mode, it retrieves the start and end dates from the frame schema.
+         * For live mode, it returns null since there is no predefined time range.
+         *
+         * This method is memoized to optimize performance, as the time range for a given context will not change during execution.
+         *
+         * @param context - Strategy, exchange, and frame identifiers
+         * @param backtest - True if backtest mode, false if live mode
+         * @returns An object containing 'from' and 'to' Date objects for backtest mode, or null for live mode
+         */
+        this._getRange = memoize(([context, backtest]) => `${context.frameName}:${backtest ? "backtest" : "live"}`, (context, backtest) => {
+            return GET_RANGE_FN(this, context, backtest);
+        });
+        /**
+         * Fetches strategy-defined runtime information for the current execution context.
+         *
+         * This method retrieves the 'info' object defined in the strategy schema, which can contain any custom data the strategy wants to track at runtime.
+         * The content of this object is not defined by the system and can be used freely by strategy implementations for monitoring, reporting, or external logic.
+         *
+         * This method is memoized to optimize performance, as the strategy info for a given context will not change during execution.
+         *
+         * @param context - Strategy, exchange, and frame identifiers
+         * @returns The 'info' object defined in the strategy schema for the given strategy, or null if not defined
+         */
+        this._getInfo = memoize(([context]) => context.strategyName, (context) => {
+            return GET_INFO_FN(this, context);
+        });
+        /**
+         * Fetches comprehensive runtime information for a given symbol and strategy context, including current price, timestamp, and strategy-specific info.
+         *
+         * This method aggregates data from multiple sources (time, price, frame schema, strategy schema) to provide a complete picture of the current runtime state for a strategy tick.
+         *
+         * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+         * @param context - Strategy, exchange, and frame identifiers
+         * @param backtest - True if backtest mode, false if live mode
+         * @returns An object containing symbol, time range, strategy-defined info, context, timestamp, current price, and backtest flag
+         */
+        this.getRuntimeInfo = async (symbol, context, backtest) => {
+            this.loggerService.log("runtimeMetaService getRuntimeInfo", {
+                symbol,
+                context,
+                backtest,
+            });
+            const timestamp = await this.timeMetaService.getTimestamp(symbol, context, backtest);
+            const when = new Date(timestamp);
+            const currentPrice = await GET_PRICE_FN(this, symbol, context, backtest);
+            const range = this._getRange(context, backtest);
+            const info = this._getInfo(context);
+            return {
+                symbol,
+                range,
+                info,
+                context,
+                backtest,
+                when,
+                currentPrice,
+            };
+        };
+    }
+});
+
 {
     provide(TYPES.loggerService, () => new LoggerService());
 }
@@ -36809,6 +36980,7 @@ class NotificationHelperService {
     provide(TYPES.contextMetaService, () => new ContextMetaService());
     provide(TYPES.priceMetaService, () => new PriceMetaService());
     provide(TYPES.timeMetaService, () => new TimeMetaService());
+    provide(TYPES.runtimeMetaService, () => new RuntimeMetaService());
 }
 {
     provide(TYPES.sizingGlobalService, () => new SizingGlobalService());
@@ -36912,6 +37084,7 @@ const metaServices = {
     timeMetaService: inject(TYPES.timeMetaService),
     priceMetaService: inject(TYPES.priceMetaService),
     contextMetaService: inject(TYPES.contextMetaService),
+    runtimeMetaService: inject(TYPES.runtimeMetaService),
 };
 const globalServices = {
     sizingGlobalService: inject(TYPES.sizingGlobalService),
@@ -64567,6 +64740,20 @@ const CRON_METHOD_NAME_TICK = "CronUtils._tick";
 const CRON_METHOD_NAME_ENABLE = "CronUtils.enable";
 const CRON_METHOD_NAME_DISABLE = "CronUtils.disable";
 const CRON_METHOD_NAME_DISPOSE = "CronUtils.dispose";
+/**
+ * Watchdog timeout (ms) for a single cron handler invocation.
+ *
+ * A handler that does not settle within this window is treated as failed:
+ * `_runEntry` races `entry.handler(info)` against this `sleep` and, when the
+ * timeout wins, throws into the same `catch` as any other handler error —
+ * surfacing `failed = true`, logging a warning, and (for periodic entries)
+ * rolling back the watermark so the boundary is retried on the next tick.
+ *
+ * This guards the `singlerun`-serialised tick pipeline against a handler that
+ * never resolves (a lost `resolve`, a hung promise with no timeout of its
+ * own): without it such a handler would stall every subsequent tick forever.
+ */
+const CRON_HANDLER_TIMEOUT = 120000;
 /**
  * Local logger instance.
  *
@@ -64575,6 +64762,20 @@ const CRON_METHOD_NAME_DISPOSE = "CronUtils.dispose";
  * being bootstrapped — `Cron` can be imported and used in isolation.
  */
 const LOGGER_SERVICE$1 = new LoggerService();
+/**
+ * Local runtime-meta-service instance.
+ *
+ * Like {@link LOGGER_SERVICE}, instantiated directly via `new` rather than
+ * resolved from the DI container so `CronUtils` carries no compile-time
+ * dependency on a bootstrapped framework. `RuntimeMetaService` is built with
+ * the `singleton` HOF from `di-singleton`, so `new RuntimeMetaService()`
+ * returns the one shared singleton proxy — the same instance the rest of the
+ * framework injects — and resolves its own dependencies lazily on first use.
+ *
+ * Used by {@link CronUtils._runEntry} to assemble the {@link IRuntimeInfo}
+ * snapshot handed to each cron handler.
+ */
+const RUNTIME_META_SERVICE = new RuntimeMetaService();
 /**
  * Utility class for registering periodic tasks that fire on candle-interval
  * boundaries of the virtual time produced by parallel backtests.
@@ -64597,8 +64798,8 @@ const LOGGER_SERVICE$1 = new LoggerService();
  * Cron.register({
  *   name: "tg-signal-parser",
  *   interval: "1h",
- *   handler: async (symbol, when, backtest) => {
- *     await parseTelegramSignalsToMongo(when);
+ *   handler: async (info) => {
+ *     await parseTelegramSignalsToMongo(info.when);
  *   },
  * });
  *
@@ -64640,12 +64841,15 @@ class CronUtils {
          * - Fire-once global: `${name}:once:g${generation}`.
          * - Fire-once fan-out: `${name}:once:${symbol}:g${generation}`.
          *
-         * Value is the shared in-flight handler promise. Every parallel `tick` for
-         * the same slot key awaits this exact promise (mutex semantics) and is
-         * released together when it settles. `_inFlight` is owned exclusively by
-         * `_runEntry` — `clear()` does **not** touch it, so the singleshot promise
-         * survives concurrent `clear` calls and continues to coordinate parallel
-         * ticks until it settles.
+         * Value is the shared in-flight handler promise. It resolves to a `boolean`
+         * "failed" flag (`true` when the handler — or the runtime-info assembly —
+         * threw), which `_tick` uses to roll back the periodic watermark of the slot
+         * it opened so a failed boundary is retried. Every parallel `tick` for the
+         * same slot key awaits this exact promise (mutex semantics) and is released
+         * together when it settles. `_inFlight` is owned exclusively by `_runEntry` —
+         * `clear()` does **not** touch it, so the singleshot promise survives
+         * concurrent `clear` calls and continues to coordinate parallel ticks until
+         * it settles.
          */
         this._inFlight = new Map();
         /**
@@ -64689,9 +64893,12 @@ class CronUtils {
          *
          * Written synchronously in `_tick` at slot-open time (before the `await`),
          * so a still-in-flight handler does not let a later tick re-open the same
-         * (or an already-passed) boundary. Fire-once entries never touch this map —
-         * they use `_firedOnce`. Pruned by `_clearBoundaryFor` on
-         * `register`/`unregister` and wiped by `dispose`.
+         * (or an already-passed) boundary. If that handler then **fails**, the
+         * advance is rolled back after the slot settles — the prior value is restored
+         * (or the key deleted if there was none) — so the failed boundary is retried
+         * on the next tick, mirroring catch-up of a skipped boundary. Fire-once
+         * entries never touch this map — they use `_firedOnce`. Pruned by
+         * `_clearBoundaryFor` on `register`/`unregister` and wiped by `dispose`.
          */
         this._lastBoundary = new Map();
         /**
@@ -64711,7 +64918,7 @@ class CronUtils {
          *   name: "fetch-funding",
          *   interval: "8h",
          *   symbols: ["BTCUSDT", "ETHUSDT"],
-         *   handler: async (symbol, when, backtest) => { ... },
+         *   handler: async (info) => { ... },
          * });
          * // Later:
          * dispose();
@@ -64831,7 +65038,7 @@ class CronUtils {
          * 4. **Fire-once** (`entry.interval === undefined`):
          *    - If the entry's fired-once key is already in `_firedOnce`, skip.
          *    - Slot key: `${name}:once` (+ scope) (+ gen).
-         *    - `aligned` = the 1-minute-aligned `when` from step 0.
+         *    - `alignedMs` = the 1-minute-aligned `when` from step 0 (`ts`).
          * 5. **Periodic** (`entry.interval` set):
          *    - Align `when` to the entry's interval via {@link alignToInterval} to
          *      get `alignedMs`, the boundary this tick belongs to.
@@ -64853,32 +65060,44 @@ class CronUtils {
          *      handler is still in flight.
          *    - Slot key: `${name}:${alignedMs}` (+ scope) (+ gen).
          * 6. Singleshot per slot key: look up the slot in `_inFlight`. If a promise
-         *    already exists, `await` the same promise. Otherwise invoke
-         *    `entry.handler`, store the promise, and `await` it. The slot is
-         *    removed in `.finally()` so the next boundary creates a fresh promise;
-         *    for fire-once entries the fired-once key is also added to
-         *    `_firedOnce` on success so subsequent ticks skip it.
+         *    already exists, `await` the same promise. Otherwise open the slot via
+         *    {@link _runEntry} — which assembles the {@link IRuntimeInfo} snapshot
+         *    (from `symbol`, `context`, `backtest`) and invokes `entry.handler(info)`
+         *    — store the promise, and `await` it. The slot is removed in `.finally()`
+         *    so the next boundary creates a fresh promise; for fire-once entries the
+         *    fired-once key is also added to `_firedOnce` on success so subsequent
+         *    ticks skip it.
+         * 7. After `await Promise.all`, roll back the watermark for every **periodic**
+         *    slot this tick *opened* (not the ones whose in-flight promise it reused)
+         *    whose handler reported failure, so the next tick re-opens and re-runs
+         *    that boundary.
          *
          * Errors thrown by `handler` are caught, logged via `console.error`, and
          * **not** rethrown — a failing handler must not break the per-symbol
          * tick loop or unblock other parallel backtests with an unhandled
          * rejection. A failed fire-once handler is **not** marked as fired and
-         * will retry on the next tick.
+         * will retry on the next tick. A failed **periodic** handler likewise
+         * retries: the boundary watermark advanced at slot-open time is rolled back
+         * after the slot settles (step 7), so the next tick re-opens that boundary.
          *
          * Requires active method context and execution context.
          *
          * @param symbol - Trading symbol from the current tick.
          * @param when - Virtual time of the current tick.
          * @param backtest - `true` for backtest ticks, `false` for live ticks.
-         *   Forwarded as the third argument to `entry.handler`. Only the value
-         *   from the tick that **opens** a given slot is observed by all parallel
-         *   awaiters of that slot.
+         *   Forwarded to {@link _runEntry} and surfaced as `info.backtest`. Only the
+         *   value from the tick that **opens** a given slot is observed by all
+         *   parallel awaiters of that slot.
+         * @param context - Strategy/exchange/frame identifiers from the originating
+         *   lifecycle event, forwarded to `RuntimeMetaService.getRuntimeInfo` to
+         *   build the {@link IRuntimeInfo} snapshot passed to the handler.
          * @throws Error if method or execution context is missing.
          */
-        this._tick = async (symbol, when, backtest) => {
+        this._tick = async (symbol, when, backtest, context) => {
             LOGGER_SERVICE$1.debug(CRON_METHOD_NAME_TICK, {
                 symbol,
                 when,
+                context,
             });
             if (!MethodContextService.hasContext()) {
                 throw new Error("CronUtils _tick requires method context");
@@ -64888,6 +65107,10 @@ class CronUtils {
             }
             const ts = alignToInterval(when, "1m").getTime();
             const taskList = [];
+            // Periodic slots THIS tick actually opened (the `!pending` branch), tracked
+            // for watermark rollback on failure. See {@link IOpenedSlot} for what is and
+            // is not recorded here and why.
+            const openedList = [];
             for (const { entry, generation } of this._entries.values()) {
                 if (entry.symbols?.length && !entry.symbols.includes(symbol)) {
                     continue;
@@ -64895,7 +65118,6 @@ class CronUtils {
                 const perSymbol = !!entry.symbols?.length;
                 const scope = perSymbol ? `:${symbol}` : "";
                 const genSuffix = `:g${generation}`;
-                let aligned;
                 let alignedMs;
                 let slotKey;
                 let firedKey;
@@ -64907,15 +65129,13 @@ class CronUtils {
                     if (this._firedOnce.has(onceKey)) {
                         continue;
                     }
-                    aligned = alignToInterval(when, "1m");
                     alignedMs = ts;
                     slotKey = `${entry.name}:once${scope}${genSuffix}`;
                     firedKey = onceKey;
                     boundaryKey = null;
                 }
                 else {
-                    aligned = alignToInterval(when, entry.interval);
-                    alignedMs = aligned.getTime();
+                    alignedMs = alignToInterval(when, entry.interval).getTime();
                     boundaryKey = `${entry.name}${scope}${genSuffix}`;
                     const lastBoundary = this._lastBoundary.get(boundaryKey);
                     // Fire when the tick's aligned boundary has advanced past the last one
@@ -64933,16 +65153,70 @@ class CronUtils {
                     // Advance the watermark synchronously at slot-open time, before the
                     // await below. Otherwise a later tick on the same (or an already
                     // crossed) boundary, arriving while this handler is still in flight,
-                    // would see the stale watermark and open a duplicate slot.
+                    // would see the stale watermark and open a duplicate slot. The advance
+                    // is rolled back after the slot settles if the handler failed (see the
+                    // post-await loop below), so a failed boundary is retried next tick.
                     if (boundaryKey !== null) {
+                        // Capture the pre-advance value so it can be restored verbatim on
+                        // failure (undefined => the boundary had never opened => delete the
+                        // key on rollback). Read fresh here rather than reusing `lastBoundary`
+                        // above to keep the value↔slot binding local and obvious; there is no
+                        // `await` between the two reads, so they are identical.
+                        const prevBoundary = this._lastBoundary.get(boundaryKey);
                         this._lastBoundary.set(boundaryKey, alignedMs);
+                        pending = this._runEntry(entry, symbol, alignedMs, slotKey, firedKey, backtest, context);
+                        this._inFlight.set(slotKey, pending);
+                        openedList.push({ boundaryKey, prevBoundary, pending });
+                    }
+                    else {
+                        pending = this._runEntry(entry, symbol, alignedMs, slotKey, firedKey, backtest, context);
+                        this._inFlight.set(slotKey, pending);
                     }
-                    pending = this._runEntry(entry, symbol, aligned, alignedMs, slotKey, firedKey, backtest);
-                    this._inFlight.set(slotKey, pending);
                 }
                 taskList.push(pending);
             }
-            await Promise.all(taskList);
+            {
+                // Watchdog: warn (do not interrupt) if the slots this tick is awaiting
+                // have not settled within CRON_HANDLER_TIMEOUT. We deliberately keep
+                // awaiting Promise.all so the singlerun pipeline stays serialised and no
+                // duplicate/zombie slots are spawned — the timer only surfaces the stall.
+                // Use a real setTimeout/clearTimeout (not sleep) so the alarm is cancelled
+                // the instant Promise.all resolves, rather than lingering for the full
+                // timeout on every fast tick.
+                const timer = setTimeout(() => {
+                    const message = `${CRON_METHOD_NAME_TICK} timed out after ${CRON_HANDLER_TIMEOUT}ms`;
+                    const payload = { symbol, when, context };
+                    LOGGER_SERVICE$1.warn(message, payload);
+                    console.error(message, payload);
+                    errorEmitter.next(new Error(message));
+                }, CRON_HANDLER_TIMEOUT);
+                try {
+                    await Promise.all(taskList);
+                }
+                finally {
+                    clearTimeout(timer);
+                }
+            }
+            // Roll back the watermark for any periodic slot THIS tick opened whose
+            // handler failed, so the next tick re-opens the same boundary and retries
+            // it — mirroring how a skipped boundary is later caught up. Restoring
+            // `prevBoundary` (or deleting the key when it was `undefined`) re-arms the
+            // strict-`>` gate without disturbing any earlier already-fired boundary.
+            // `await pending` is cheap — every promise already settled in `Promise.all`
+            // above; we re-await via `openedList` because its entries (opened slots
+            // only) do not line up with `taskList` indices.
+            for (const { boundaryKey, prevBoundary, pending } of openedList) {
+                const failed = await pending;
+                if (!failed) {
+                    continue;
+                }
+                if (prevBoundary === undefined) {
+                    this._lastBoundary.delete(boundaryKey);
+                }
+                else {
+                    this._lastBoundary.set(boundaryKey, prevBoundary);
+                }
+            }
         };
         /**
          * Subscribe `Cron` to the engine's strategy lifecycle subjects so registered
@@ -64957,7 +65231,11 @@ class CronUtils {
          *
          * All four subjects are subscribed to a single `singlerun`-wrapped
          * handler that builds `_tick(event.symbol, new Date(event.timestamp),
-         * event.backtest)`. `singlerun` merges the four streams into one serial
+         * event.backtest, { strategyName, exchangeName, frameName })`. The context
+         * object is read uniformly from the event — every contract carries
+         * `strategyName`, `exchangeName` and `frameName` at the top level (Active /
+         * Schedule contracts gained `frameName` for exactly this reason), so no
+         * per-event branching is needed. `singlerun` merges the four streams into one serial
          * queue: at most one `_tick` runs at a time, the next waits. This matters
          * because the engine can emit `beforeStart` and an immediate `idlePing`
          * on the very same minute, and concurrent `_tick`s on the same
@@ -64993,7 +65271,11 @@ class CronUtils {
         this.enable = singleshot(() => {
             LOGGER_SERVICE$1.info(CRON_METHOD_NAME_ENABLE);
             const handleTick = singlerun(async (event) => {
-                return await this._tick(event.symbol, new Date(event.timestamp), event.backtest);
+                return await this._tick(event.symbol, new Date(event.timestamp), event.backtest, {
+                    strategyName: event.strategyName,
+                    exchangeName: event.exchangeName,
+                    frameName: event.frameName,
+                });
             });
             const unBeforeStart = beforeStartSubject.subscribe(handleTick);
             const unIdlePing = idlePingSubject.subscribe(handleTick);
@@ -65096,25 +65378,51 @@ class CronUtils {
     /**
      * Build the singleshot promise for a single in-flight slot.
      *
-     * Invokes `entry.handler(symbol, aligned, backtest)`, swallows and logs
-     * any error via `console.error`, and clears the `_inFlight` slot
-     * in `.finally()` so the next boundary produces a fresh promise. For
-     * fire-once entries `firedKey` is added to `_firedOnce` on success so
-     * subsequent ticks skip it.
-     *
+     * Assembles the {@link IRuntimeInfo} snapshot via
+     * `RuntimeMetaService.getRuntimeInfo(symbol, context, backtest)` and invokes
+     * `entry.handler(info)`. Logs any error via `console.error` and **returns** a
+     * `failed` boolean (`true` when the handler — or the runtime-info assembly —
+     * threw) so the caller (`_tick`) can roll back the periodic watermark of the
+     * slot it opened and retry that boundary. The error is **not** rethrown, so a
+     * failing handler never produces an unhandled rejection. Clears the
+     * `_inFlight` slot in `.finally()` so the next boundary produces a fresh
+     * promise. For fire-once entries `firedKey` is added to `_firedOnce` on
+     * success so subsequent ticks skip it.
+     *
+     * `getRuntimeInfo` is the user-facing aggregator: its sub-fetches (range,
+     * info, price) are individually wrapped in `trycatch` with `null` fallbacks,
+     * so it almost never throws for missing data. Whatever does throw — the
+     * handler, or in rare cases `getRuntimeInfo` — is caught here and reported via
+     * the returned `failed` flag; the watermark rollback treats both identically.
+     *
+     * @param context - Strategy/exchange/frame identifiers from the originating
+     *   lifecycle event, forwarded to `getRuntimeInfo` to resolve `range`/`info`.
      * @param firedKey - Key to add to `_firedOnce` on success, or `null` for
      *   periodic entries (which never populate `_firedOnce`).
-     * @param backtest - Value forwarded as the third handler argument; the
-     *   "winner" tick's flag is what all parallel awaiters of this slot see.
+     * @param backtest - Forwarded to `getRuntimeInfo` and surfaced as
+     *   `info.backtest`; the "winner" tick's flag is what all parallel awaiters
+     *   of this slot see.
+     * @returns `true` if the handler (or `getRuntimeInfo`) threw, `false` on
+     *   success. `_tick` uses this to decide whether to roll back the watermark.
      */
-    async _runEntry(entry, symbol, aligned, alignedMs, slotKey, firedKey, backtest) {
+    async _runEntry(entry, symbol, alignedMs, slotKey, firedKey, backtest, context) {
         let failed = false;
         try {
-            await entry.handler(symbol, aligned, backtest);
+            const info = await RUNTIME_META_SERVICE.getRuntimeInfo(symbol, context, backtest);
+            await entry.handler(info);
         }
-        catch (err) {
+        catch (error) {
             failed = true;
-            console.error(`${CRON_METHOD_NAME_TICK} entry "${entry.name}" failed`, { symbol, alignedMs, err });
+            const message = `${CRON_METHOD_NAME_TICK} entry "${entry.name}" failed`;
+            const payload = {
+                symbol,
+                alignedMs,
+                error: errorData(error),
+                message: getErrorMessage(error),
+            };
+            LOGGER_SERVICE$1.warn(message, payload);
+            console.error(message, payload);
+            errorEmitter.next(error);
         }
         finally {
             this._inFlight.delete(slotKey);
@@ -65122,6 +65430,7 @@ class CronUtils {
                 this._firedOnce.add(firedKey);
             }
         }
+        return failed;
     }
 }
 /**
@@ -65135,7 +65444,7 @@ class CronUtils {
  * Cron.register({
  *   name: "tg-parser",
  *   interval: "1h",
- *   handler: async (symbol, when, backtest) => { ... },
+ *   handler: async (info) => { ... },
  * });
  * ```
  */