backtest-kit 11.0.0 → 11.3.0

package/README.md

@@ -79,7 +79,7 @@ Install the core library and peer dependencies manually. Use this approach when
 - 🔌 **Pluggable**: Custom data sources (CCXT), persistence (file/Redis), and sizing calculators.
 - 🗃️ **Transactional Live Orders**: Broker adapter intercepts every trade mutation before internal state changes — exchange rejection rolls back the operation atomically.
 - ⏰ **Built-in Crontab**: Register periodic or fire-once jobs that fire on virtual-time boundaries with singleshot coordination across parallel backtests — one handler invocation per boundary, no double-fires.
-- 🧪 **Tested**: 740+ unit/integration tests for validation, recovery, and events.
+- 🧪 **Tested**: 770+ unit/integration tests for validation, recovery, and events.
 - 🔓 **Self hosted**: Zero dependency on third-party node_modules or platforms; run entirely in your own environment.
 
 ## 📋 Supported Order Types
@@ -1983,7 +1983,7 @@ Python-based (WASI) strategy that uses EMA(9) and EMA(21) crossover signals exec
 
 ## ✅ Tested & Reliable
 
-740+ tests cover validation, recovery, reports, and events.
+770+ tests cover validation, recovery, reports, and events.
 
 ## 🤝 Contribute
 

package/build/index.cjs

@@ -23816,6 +23816,7 @@ let ReportStorage$a = class ReportStorage {
                 sortinoRatio: null,
                 calmarRatio: null,
                 recoveryFactor: null,
+                expectancy: null,
             };
         }
         // Valid signal set — those with usable pendingAt AND closeTimestamp. Single source
@@ -23938,6 +23939,12 @@ let ReportStorage$a = class ReportStorage {
         const certaintyRatio = canComputeRatios && Math.abs(avgLoss) > STDDEV_EPSILON$2 && avgLoss < 0
             ? avgWin / Math.abs(avgLoss)
             : null;
+        // Per-trade Expectancy: winProb*avgWin + lossProb*avgLoss. Break-even trades
+        // contribute 0 (they're excluded from both probabilities). N-gated like the
+        // other ratios — on a tiny sample the per-trade EV is too noisy to publish.
+        const expectancy = canComputeRatios && totalSignals > 0
+            ? (wins.length / totalSignals) * avgWin + (losses.length / totalSignals) * avgLoss
+            : null;
         // Average peak/fall PNL — over validSignals; only signals that actually have the
         // value contribute (no zero dilution from missing peakProfit/maxDrawdown).
         const peakValues = validSignals
@@ -24002,6 +24009,7 @@ let ReportStorage$a = class ReportStorage {
             sortinoRatio: isUnsafe$4(sortinoRatio) ? null : sortinoRatio,
             calmarRatio: isUnsafe$4(calmarRatio) ? null : calmarRatio,
             recoveryFactor: isUnsafe$4(recoveryFactor) ? null : recoveryFactor,
+            expectancy: isUnsafe$4(expectancy) ? null : expectancy,
         };
     }
     /**
@@ -24051,6 +24059,7 @@ let ReportStorage$a = class ReportStorage {
             `**Sortino Ratio:** ${stats.sortinoRatio === null ? "N/A" : `${stats.sortinoRatio.toFixed(3)} (higher is better)`}`,
             `**Calmar Ratio:** ${stats.calmarRatio === null ? "N/A" : `${stats.calmarRatio.toFixed(3)} (higher is better)`}`,
             `**Recovery Factor:** ${stats.recoveryFactor === null ? "N/A" : `${stats.recoveryFactor.toFixed(3)} (higher is better)`}`,
+            `**Expectancy:** ${stats.expectancy === null ? "N/A" : `${stats.expectancy > 0 ? "+" : ""}${stats.expectancy.toFixed(3)}% (higher is better)`}`,
             "",
             `*Win Rate: reliable above 200+ signals; below 30 signals a single streak can shift it by 10-20%.*`,
             `*Sharpe Ratio: below 1.0 is poor, 1.0-2.0 is acceptable, above 2.0 is strong. Requires 30+ signals.*`,
@@ -24060,6 +24069,7 @@ let ReportStorage$a = class ReportStorage {
             `*Expected Yearly Returns: compounded geometric return from the equity curve, annualized by tradesPerYear. Same gating as Annualized Sharpe. Capped at ±${MAX_EXPECTED_YEARLY_RETURNS$2}% — values above the cap return N/A.*`,
             `*Calmar Ratio: below 0.5 is poor, 0.5-1.0 is acceptable, above 1.0 is strong. Denominator is compounded equity-curve max drawdown. Capped at ±${MAX_CALMAR_RATIO$2}.*`,
             `*Recovery Factor: below 1.0 means total profit does not cover max drawdown. Above 3.0 is considered good. Uses compounded total return as numerator.*`,
+            `*Expectancy: per-trade expected value (winProb × avgWin + lossProb × avgLoss). Positive = profitable on average per trade. Break-even trades contribute 0.*`,
             `*All metrics require 100+ signals to be statistically reliable. Annualized metrics assume the observed trading frequency and market conditions persist year-round.*`,
             `*IMPORTANT: Equity curve, Expected Yearly Returns, Calmar, Recovery and Max Drawdown all assume **100% capital allocation per trade** (no sizing, no portfolio fraction). Per-trade pnlPercentage is treated as a return on full equity. If your strategy risks X% of capital per trade, the realized portfolio return / drawdown will be roughly X/100 of the reported figures. The framework does not track portfolio-level sizing, so these metrics represent a theoretical upper bound under full allocation.*`,
             `*Negative values for Sharpe / Sortino / Calmar / Recovery / Expected Yearly Returns indicate a losing strategy (avgPnl < 0 or totalPnl < 0). "Higher is better" still applies — closer to zero is less bad, positive is profitable.*`,
@@ -24685,6 +24695,7 @@ let ReportStorage$9 = class ReportStorage {
                 sortinoRatio: null,
                 calmarRatio: null,
                 recoveryFactor: null,
+                expectancy: null,
             };
         }
         const closedEvents = this._eventList.filter((e) => e.action === "closed");
@@ -24755,6 +24766,7 @@ let ReportStorage$9 = class ReportStorage {
         // so the report doesn't surface certainty on a handful of trades while
         // withholding the rest.
         let certaintyRatio = null;
+        let expectancy = null;
         if (canComputeRatios && totalClosed > 0) {
             const wins = validClosed.filter((e) => e.pnl > 0);
             const losses = validClosed.filter((e) => e.pnl < 0);
@@ -24769,6 +24781,9 @@ let ReportStorage$9 = class ReportStorage {
             certaintyRatio = Math.abs(avgLoss) > STDDEV_EPSILON$1 && avgLoss < 0
                 ? avgWin / Math.abs(avgLoss)
                 : null;
+            // Per-trade Expectancy: winProb*avgWin + lossProb*avgLoss. Break-even
+            // trades contribute 0 (excluded from both probabilities).
+            expectancy = (wins.length / totalClosed) * avgWin + (losses.length / totalClosed) * avgLoss;
         }
         // Average only over signals that have the value — do not dilute the mean with zeros.
         // Use validClosed to keep all metric denominators consistent.
@@ -24872,6 +24887,7 @@ let ReportStorage$9 = class ReportStorage {
             sortinoRatio: isUnsafe$3(sortinoRatio) ? null : sortinoRatio,
             calmarRatio: isUnsafe$3(calmarRatio) ? null : calmarRatio,
             recoveryFactor: isUnsafe$3(recoveryFactor) ? null : recoveryFactor,
+            expectancy: isUnsafe$3(expectancy) ? null : expectancy,
         };
     }
     /**
@@ -24921,6 +24937,7 @@ let ReportStorage$9 = class ReportStorage {
             `**Sortino Ratio:** ${stats.sortinoRatio === null ? "N/A" : `${stats.sortinoRatio.toFixed(3)} (higher is better)`}`,
             `**Calmar Ratio:** ${stats.calmarRatio === null ? "N/A" : `${stats.calmarRatio.toFixed(3)} (higher is better)`}`,
             `**Recovery Factor:** ${stats.recoveryFactor === null ? "N/A" : `${stats.recoveryFactor.toFixed(3)} (higher is better)`}`,
+            `**Expectancy:** ${stats.expectancy === null ? "N/A" : `${stats.expectancy > 0 ? "+" : ""}${stats.expectancy.toFixed(3)}% (higher is better)`}`,
             "",
             `*Win Rate: reliable above 200+ signals; below 30 signals a single streak can shift it by 10-20%.*`,
             `*Sharpe Ratio: below 1.0 is poor, 1.0-2.0 is acceptable, above 2.0 is strong. Requires 30+ signals.*`,
@@ -24930,6 +24947,7 @@ let ReportStorage$9 = class ReportStorage {
             `*Expected Yearly Returns: compounded geometric return from the equity curve, annualized by tradesPerYear. Same gating as Annualized Sharpe. Capped at ±${MAX_EXPECTED_YEARLY_RETURNS$1}% — values above the cap return N/A.*`,
             `*Calmar Ratio: below 0.5 is poor, 0.5-1.0 is acceptable, above 1.0 is strong. Denominator is compounded equity-curve max drawdown. Capped at ±${MAX_CALMAR_RATIO$1}.*`,
             `*Recovery Factor: below 1.0 means total profit does not cover max drawdown. Above 3.0 is considered good. Uses compounded total return as numerator.*`,
+            `*Expectancy: per-trade expected value (winProb × avgWin + lossProb × avgLoss). Positive = profitable on average per trade. Break-even trades contribute 0.*`,
             `*All metrics require 100+ signals to be statistically reliable. Annualized metrics assume the observed trading frequency and market conditions persist year-round.*`,
             `*IMPORTANT: Equity curve, Expected Yearly Returns, Calmar, Recovery and Max Drawdown all assume **100% capital allocation per trade** (no sizing, no portfolio fraction). Per-trade pnlPercentage is treated as a return on full equity. If your strategy risks X% of capital per trade, the realized portfolio return / drawdown will be roughly X/100 of the reported figures. The framework does not track portfolio-level sizing, so these metrics represent a theoretical upper bound under full allocation.*`,
             `*Negative values for Sharpe / Sortino / Calmar / Recovery / Expected Yearly Returns indicate a losing strategy (avgPnl < 0 or totalPnl < 0). "Higher is better" still applies — closer to zero is less bad, positive is profitable.*`,
@@ -27127,11 +27145,15 @@ class HeatmapStorage {
                 : null;
             portfolioTotalTrades = symbols.reduce((acc, s) => acc + s.totalTrades, 0);
         }
-        // Pooled Sharpe over all returns across symbols. NOTE: this is NOT a Markowitz
-        // portfolio Sharpe — it ignores cross-symbol correlations and treats trades as a
-        // single pooled sample. Gated by MIN_SIGNALS_FOR_RATIOS so a 2-trade pool cannot
-        // produce a noisy ±Sharpe.
+        // Pooled metrics over all returns across symbols. NOT a Markowitz portfolio —
+        // ignores cross-symbol correlations, treats trades as a single pooled sample.
+        // Gated by MIN_SIGNALS_FOR_RATIOS so a tiny pool can't produce noisy ratios.
         let portfolioSharpeRatio = null;
+        let portfolioStdDev = null;
+        let portfolioSortinoRatio = null;
+        let portfolioExpectancy = null;
+        let portfolioCalmarRatio = null;
+        let portfolioRecoveryFactor = null;
         const allReturns = [];
         for (const signals of this.symbolData.values()) {
             for (const s of signals) {
@@ -27142,10 +27164,63 @@ class HeatmapStorage {
             const portfolioAvg = allReturns.reduce((acc, r) => acc + r, 0) / allReturns.length;
             const portfolioVariance = allReturns.reduce((acc, r) => acc + Math.pow(r - portfolioAvg, 2), 0) /
                 (allReturns.length - 1);
-            const portfolioStdDev = Math.sqrt(portfolioVariance);
+            const stdDev = Math.sqrt(portfolioVariance);
             // STDDEV_EPSILON guard — same protection as per-symbol Sharpe.
-            if (portfolioStdDev > STDDEV_EPSILON) {
-                portfolioSharpeRatio = portfolioAvg / portfolioStdDev;
+            portfolioStdDev = stdDev;
+            if (stdDev > STDDEV_EPSILON) {
+                portfolioSharpeRatio = portfolioAvg / stdDev;
+            }
+            // Canonical Sortino: downside dev = √( Σ min(0, r)² / N_total ), MAR=0.
+            const negativeReturns = allReturns.filter((r) => r < 0);
+            if (negativeReturns.length > 0) {
+                const downsideVariance = negativeReturns.reduce((acc, r) => acc + r * r, 0) / allReturns.length;
+                const downsideDeviation = Math.sqrt(downsideVariance);
+                if (downsideDeviation > STDDEV_EPSILON) {
+                    portfolioSortinoRatio = portfolioAvg / downsideDeviation;
+                }
+            }
+            // Pooled Expectancy: per-trade EV = winProb*avgWin + lossProb*avgLoss.
+            // Break-even trades contribute 0 (excluded from both probs).
+            const wins = allReturns.filter((r) => r > 0);
+            const losses = allReturns.filter((r) => r < 0);
+            const total = allReturns.length;
+            const avgWin = wins.length > 0 ? wins.reduce((a, b) => a + b, 0) / wins.length : 0;
+            const avgLoss = losses.length > 0 ? losses.reduce((a, b) => a + b, 0) / losses.length : 0;
+            if (wins.length > 0 || losses.length > 0) {
+                portfolioExpectancy = (wins.length / total) * avgWin + (losses.length / total) * avgLoss;
+            }
+            // Pooled equity-curve max drawdown (compounded).
+            let equity = 1;
+            let peak = 1;
+            let maxDD = 0;
+            let blown = false;
+            for (const r of allReturns) {
+                equity *= 1 + r / 100;
+                if (equity <= 0) {
+                    maxDD = 100;
+                    blown = true;
+                    break;
+                }
+                if (equity > peak)
+                    peak = equity;
+                const dd = ((peak - equity) / peak) * 100;
+                if (dd > maxDD)
+                    maxDD = dd;
+            }
+            const equityFinal = blown ? 0 : equity;
+            // Pooled Calmar / Recovery, both clamped at ±MAX_CALMAR_RATIO and using
+            // compounded total return / DD. Same shape as per-symbol formula.
+            if (maxDD > 0) {
+                if (!blown) {
+                    const rawCalmar = ((equityFinal - 1) * 100) / maxDD;
+                    portfolioCalmarRatio = Math.max(-MAX_CALMAR_RATIO, Math.min(MAX_CALMAR_RATIO, rawCalmar));
+                    const rawRec = ((equityFinal - 1) * 100) / maxDD;
+                    portfolioRecoveryFactor = Math.max(-MAX_CALMAR_RATIO, Math.min(MAX_CALMAR_RATIO, rawRec));
+                }
+                else {
+                    // Blown — full loss is the only meaningful value; recovery undefined.
+                    portfolioCalmarRatio = -1; // -100 / 100
+                }
             }
         }
         // Portfolio-wide weighted average peak/fall PNL. Denominator must include only
@@ -27172,6 +27247,16 @@ class HeatmapStorage {
             portfolioAvgPeakPnl = null;
         if (isUnsafe(portfolioAvgFallPnl))
             portfolioAvgFallPnl = null;
+        if (isUnsafe(portfolioStdDev))
+            portfolioStdDev = null;
+        if (isUnsafe(portfolioSortinoRatio))
+            portfolioSortinoRatio = null;
+        if (isUnsafe(portfolioCalmarRatio))
+            portfolioCalmarRatio = null;
+        if (isUnsafe(portfolioRecoveryFactor))
+            portfolioRecoveryFactor = null;
+        if (isUnsafe(portfolioExpectancy))
+            portfolioExpectancy = null;
         return {
             symbols,
             totalSymbols,
@@ -27180,6 +27265,11 @@ class HeatmapStorage {
             portfolioTotalTrades,
             portfolioAvgPeakPnl,
             portfolioAvgFallPnl,
+            portfolioStdDev,
+            portfolioSortinoRatio,
+            portfolioCalmarRatio,
+            portfolioRecoveryFactor,
+            portfolioExpectancy,
         };
     }
     /**
@@ -27229,6 +27319,7 @@ class HeatmapStorage {
             `# Portfolio Heatmap: ${strategyName}`,
             "",
             `**Total Symbols:** ${data.totalSymbols} | **Portfolio PNL:** ${data.portfolioTotalPnl !== null ? functoolsKit.str(data.portfolioTotalPnl, "%") : "N/A"} | **Pooled Sharpe:** ${data.portfolioSharpeRatio !== null ? functoolsKit.str(data.portfolioSharpeRatio) : "N/A"} | **Total Trades:** ${data.portfolioTotalTrades} | **Avg Peak PNL:** ${data.portfolioAvgPeakPnl !== null ? functoolsKit.str(data.portfolioAvgPeakPnl, "%") : "N/A"} | **Avg Max Drawdown PNL:** ${data.portfolioAvgFallPnl !== null ? functoolsKit.str(data.portfolioAvgFallPnl, "%") : "N/A"}`,
+            `**Standard Deviation:** ${data.portfolioStdDev !== null ? functoolsKit.str(data.portfolioStdDev, "%") : "N/A"} | **Sortino Ratio:** ${data.portfolioSortinoRatio !== null ? functoolsKit.str(data.portfolioSortinoRatio) : "N/A"} | **Calmar Ratio:** ${data.portfolioCalmarRatio !== null ? functoolsKit.str(data.portfolioCalmarRatio) : "N/A"} | **Recovery Factor:** ${data.portfolioRecoveryFactor !== null ? functoolsKit.str(data.portfolioRecoveryFactor) : "N/A"} | **Expectancy:** ${data.portfolioExpectancy !== null ? functoolsKit.str(data.portfolioExpectancy, "%") : "N/A"}`,
             "",
             table,
             "",
@@ -63859,6 +63950,34 @@ class CronUtils {
          * on successful settle.
          */
         this._firedOnce = new Set();
+        /**
+         * Last interval boundary already fired per periodic slot.
+         *
+         * Key shape (no `alignedMs` segment — one entry per logical slot, not per
+         * boundary; always carries the generation suffix `:g${generation}`, and the
+         * `:${symbol}` scope only in fan-out mode):
+         * - Periodic global: `${name}${genSuffix}`.
+         * - Periodic fan-out: `${name}:${symbol}${genSuffix}`.
+         *
+         * Value is the aligned-boundary epoch ms (`alignedMs`) most recently opened
+         * for that slot. `_tick` fires a periodic entry whenever the incoming tick's
+         * aligned boundary is **strictly greater** than the stored value, instead of
+         * requiring the tick to land *exactly* on the boundary. This fixes the
+         * dropped-boundary bug: when virtual time jumps over a boundary (e.g. a
+         * `5m`-driven loop skipping from 00:14 to 00:29 never lands on the `15m`
+         * 00:15 boundary), the old `ts === alignedMs` check silently lost the tick.
+         * With the watermark, the next tick whose `alignedMs` advanced past the
+         * stored value fires once for the newest crossed boundary (catch-up
+         * collapses multiple skipped boundaries into a single invocation at the
+         * latest one).
+         *
+         * 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`.
+         */
+        this._lastBoundary = new Map();
         /**
          * Register a periodic cron entry.
          *
@@ -63904,6 +64023,7 @@ class CronUtils {
                 }
             }
             this._clearFiredOnceFor(entry.name);
+            this._clearBoundaryFor(entry.name);
             const generation = ++this._generationCounter;
             this._entries.set(entry.name, { entry, generation });
             return () => this.unregister(entry.name);
@@ -63920,6 +64040,7 @@ class CronUtils {
             LOGGER_SERVICE$1.info(CRON_METHOD_NAME_UNREGISTER, { name });
             this._entries.delete(name);
             this._clearFiredOnceFor(name);
+            this._clearBoundaryFor(name);
         };
         /**
          * Clear fire-once marks so that fire-once entries can fire again.
@@ -63996,11 +64117,24 @@ class CronUtils {
          *    - Slot key: `${name}:once` (+ scope) (+ gen).
          *    - `aligned` = the 1-minute-aligned `when` from step 0.
          * 5. **Periodic** (`entry.interval` set):
-         *    - Align `when` further to the entry's interval via {@link alignToInterval}.
-         *    - If `ts !== alignedMs`, the tick is mid-interval — skip.
-         *      (This is the "remainder === 0" boundary check from the spec;
-         *      since `ts` is already on the 1-minute boundary, the check is exact
-         *      for `1m` and consistent for higher intervals.)
+         *    - Align `when` to the entry's interval via {@link alignToInterval} to
+         *      get `alignedMs`, the boundary this tick belongs to.
+         *    - Compare against the slot's watermark in `_lastBoundary` (keyed by
+         *      `${name}` + scope + gen, without the `alignedMs` segment). If a
+         *      watermark exists and `alignedMs <= lastBoundary`, this boundary was
+         *      already fired — skip.
+         *    - This **watermark** check replaces the old exact `ts === alignedMs`
+         *      match. The exact match required virtual time to land *precisely* on
+         *      the boundary; when a tick jumped clean over a boundary (e.g. a `5m`
+         *      loop going 00:14 → 00:29 never touching the `15m` 00:15 boundary)
+         *      the boundary was silently lost. With the watermark, the first tick
+         *      whose `alignedMs` advanced past the stored value fires once, at the
+         *      newest crossed boundary (catch-up collapses several skipped
+         *      boundaries into a single invocation at the latest one).
+         *    - The watermark is advanced to `alignedMs` synchronously when the slot
+         *      is opened (before the `await`), so a concurrent tick on the same or
+         *      an already-passed boundary cannot open a duplicate slot while the
+         *      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
@@ -64049,6 +64183,9 @@ class CronUtils {
                 let alignedMs;
                 let slotKey;
                 let firedKey;
+                // Periodic-only watermark key (no `alignedMs` segment); null for
+                // fire-once entries, which coordinate via `_firedOnce` instead.
+                let boundaryKey;
                 if (entry.interval === undefined) {
                     const onceKey = `${entry.name}${scope}${genSuffix}`;
                     if (this._firedOnce.has(onceKey)) {
@@ -64058,11 +64195,18 @@ class CronUtils {
                     alignedMs = ts;
                     slotKey = `${entry.name}:once${scope}${genSuffix}`;
                     firedKey = onceKey;
+                    boundaryKey = null;
                 }
                 else {
                     aligned = alignToInterval(when, entry.interval);
                     alignedMs = aligned.getTime();
-                    if (ts !== alignedMs) {
+                    boundaryKey = `${entry.name}${scope}${genSuffix}`;
+                    const lastBoundary = this._lastBoundary.get(boundaryKey);
+                    // Fire when the tick's aligned boundary has advanced past the last one
+                    // we fired for this slot. Using `>` instead of the old `ts === alignedMs`
+                    // means a virtual-time jump that skips clean over a boundary still
+                    // fires once, at the newest crossed boundary, rather than dropping it.
+                    if (lastBoundary !== undefined && alignedMs <= lastBoundary) {
                         continue;
                     }
                     slotKey = `${entry.name}:${alignedMs}${scope}${genSuffix}`;
@@ -64070,6 +64214,13 @@ class CronUtils {
                 }
                 let pending = this._inFlight.get(slotKey);
                 if (!pending) {
+                    // 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.
+                    if (boundaryKey !== null) {
+                        this._lastBoundary.set(boundaryKey, alignedMs);
+                    }
                     pending = this._runEntry(entry, symbol, aligned, alignedMs, slotKey, firedKey, backtest);
                     this._inFlight.set(slotKey, pending);
                 }
@@ -64161,7 +64312,10 @@ class CronUtils {
          * 3. Wipes `_firedOnce` — all fire-once marks are dropped, so any future
          *    re-registration of the same `name` fires again on the next matching
          *    tick.
-         * 4. Does **not** touch `_inFlight` — in-flight handlers continue to
+         * 4. Wipes `_lastBoundary` — all periodic watermarks are dropped, so a
+         *    re-registered periodic entry starts firing from its next crossed
+         *    boundary again.
+         * 5. Does **not** touch `_inFlight` — in-flight handlers continue to
          *    settle in the background and clear their own slots via `.finally()`.
          *    Their final `_firedOnce.add(firedKey)` writes carry old-generation
          *    keys and are harmless (lookup uses the post-dispose generation).
@@ -64180,8 +64334,29 @@ class CronUtils {
             this.disable();
             this._entries.clear();
             this._firedOnce.clear();
+            this._lastBoundary.clear();
         };
     }
+    /**
+     * Garbage-collect every `_lastBoundary` key that belongs to the entry `name`
+     * (any generation, global or fan-out).
+     *
+     * Called from `register`/`unregister` alongside `_clearFiredOnceFor`. Like
+     * that helper this is memory hygiene, not correctness — the generation suffix
+     * already isolates re-registrations, so a stale watermark from an old
+     * generation can never gate a new entry.
+     */
+    _clearBoundaryFor(name) {
+        if (!name) {
+            return;
+        }
+        const prefix = `${name}:`;
+        for (const key of this._lastBoundary.keys()) {
+            if (key === name || key.startsWith(prefix)) {
+                this._lastBoundary.delete(key);
+            }
+        }
+    }
     /**
      * Garbage-collect every `_firedOnce` key that belongs to the entry `name`
      * (any generation, global or fan-out).

package/build/index.mjs

@@ -23796,6 +23796,7 @@ let ReportStorage$a = class ReportStorage {
                 sortinoRatio: null,
                 calmarRatio: null,
                 recoveryFactor: null,
+                expectancy: null,
             };
         }
         // Valid signal set — those with usable pendingAt AND closeTimestamp. Single source
@@ -23918,6 +23919,12 @@ let ReportStorage$a = class ReportStorage {
         const certaintyRatio = canComputeRatios && Math.abs(avgLoss) > STDDEV_EPSILON$2 && avgLoss < 0
             ? avgWin / Math.abs(avgLoss)
             : null;
+        // Per-trade Expectancy: winProb*avgWin + lossProb*avgLoss. Break-even trades
+        // contribute 0 (they're excluded from both probabilities). N-gated like the
+        // other ratios — on a tiny sample the per-trade EV is too noisy to publish.
+        const expectancy = canComputeRatios && totalSignals > 0
+            ? (wins.length / totalSignals) * avgWin + (losses.length / totalSignals) * avgLoss
+            : null;
         // Average peak/fall PNL — over validSignals; only signals that actually have the
         // value contribute (no zero dilution from missing peakProfit/maxDrawdown).
         const peakValues = validSignals
@@ -23982,6 +23989,7 @@ let ReportStorage$a = class ReportStorage {
             sortinoRatio: isUnsafe$4(sortinoRatio) ? null : sortinoRatio,
             calmarRatio: isUnsafe$4(calmarRatio) ? null : calmarRatio,
             recoveryFactor: isUnsafe$4(recoveryFactor) ? null : recoveryFactor,
+            expectancy: isUnsafe$4(expectancy) ? null : expectancy,
         };
     }
     /**
@@ -24031,6 +24039,7 @@ let ReportStorage$a = class ReportStorage {
             `**Sortino Ratio:** ${stats.sortinoRatio === null ? "N/A" : `${stats.sortinoRatio.toFixed(3)} (higher is better)`}`,
             `**Calmar Ratio:** ${stats.calmarRatio === null ? "N/A" : `${stats.calmarRatio.toFixed(3)} (higher is better)`}`,
             `**Recovery Factor:** ${stats.recoveryFactor === null ? "N/A" : `${stats.recoveryFactor.toFixed(3)} (higher is better)`}`,
+            `**Expectancy:** ${stats.expectancy === null ? "N/A" : `${stats.expectancy > 0 ? "+" : ""}${stats.expectancy.toFixed(3)}% (higher is better)`}`,
             "",
             `*Win Rate: reliable above 200+ signals; below 30 signals a single streak can shift it by 10-20%.*`,
             `*Sharpe Ratio: below 1.0 is poor, 1.0-2.0 is acceptable, above 2.0 is strong. Requires 30+ signals.*`,
@@ -24040,6 +24049,7 @@ let ReportStorage$a = class ReportStorage {
             `*Expected Yearly Returns: compounded geometric return from the equity curve, annualized by tradesPerYear. Same gating as Annualized Sharpe. Capped at ±${MAX_EXPECTED_YEARLY_RETURNS$2}% — values above the cap return N/A.*`,
             `*Calmar Ratio: below 0.5 is poor, 0.5-1.0 is acceptable, above 1.0 is strong. Denominator is compounded equity-curve max drawdown. Capped at ±${MAX_CALMAR_RATIO$2}.*`,
             `*Recovery Factor: below 1.0 means total profit does not cover max drawdown. Above 3.0 is considered good. Uses compounded total return as numerator.*`,
+            `*Expectancy: per-trade expected value (winProb × avgWin + lossProb × avgLoss). Positive = profitable on average per trade. Break-even trades contribute 0.*`,
             `*All metrics require 100+ signals to be statistically reliable. Annualized metrics assume the observed trading frequency and market conditions persist year-round.*`,
             `*IMPORTANT: Equity curve, Expected Yearly Returns, Calmar, Recovery and Max Drawdown all assume **100% capital allocation per trade** (no sizing, no portfolio fraction). Per-trade pnlPercentage is treated as a return on full equity. If your strategy risks X% of capital per trade, the realized portfolio return / drawdown will be roughly X/100 of the reported figures. The framework does not track portfolio-level sizing, so these metrics represent a theoretical upper bound under full allocation.*`,
             `*Negative values for Sharpe / Sortino / Calmar / Recovery / Expected Yearly Returns indicate a losing strategy (avgPnl < 0 or totalPnl < 0). "Higher is better" still applies — closer to zero is less bad, positive is profitable.*`,
@@ -24665,6 +24675,7 @@ let ReportStorage$9 = class ReportStorage {
                 sortinoRatio: null,
                 calmarRatio: null,
                 recoveryFactor: null,
+                expectancy: null,
             };
         }
         const closedEvents = this._eventList.filter((e) => e.action === "closed");
@@ -24735,6 +24746,7 @@ let ReportStorage$9 = class ReportStorage {
         // so the report doesn't surface certainty on a handful of trades while
         // withholding the rest.
         let certaintyRatio = null;
+        let expectancy = null;
         if (canComputeRatios && totalClosed > 0) {
             const wins = validClosed.filter((e) => e.pnl > 0);
             const losses = validClosed.filter((e) => e.pnl < 0);
@@ -24749,6 +24761,9 @@ let ReportStorage$9 = class ReportStorage {
             certaintyRatio = Math.abs(avgLoss) > STDDEV_EPSILON$1 && avgLoss < 0
                 ? avgWin / Math.abs(avgLoss)
                 : null;
+            // Per-trade Expectancy: winProb*avgWin + lossProb*avgLoss. Break-even
+            // trades contribute 0 (excluded from both probabilities).
+            expectancy = (wins.length / totalClosed) * avgWin + (losses.length / totalClosed) * avgLoss;
         }
         // Average only over signals that have the value — do not dilute the mean with zeros.
         // Use validClosed to keep all metric denominators consistent.
@@ -24852,6 +24867,7 @@ let ReportStorage$9 = class ReportStorage {
             sortinoRatio: isUnsafe$3(sortinoRatio) ? null : sortinoRatio,
             calmarRatio: isUnsafe$3(calmarRatio) ? null : calmarRatio,
             recoveryFactor: isUnsafe$3(recoveryFactor) ? null : recoveryFactor,
+            expectancy: isUnsafe$3(expectancy) ? null : expectancy,
         };
     }
     /**
@@ -24901,6 +24917,7 @@ let ReportStorage$9 = class ReportStorage {
             `**Sortino Ratio:** ${stats.sortinoRatio === null ? "N/A" : `${stats.sortinoRatio.toFixed(3)} (higher is better)`}`,
             `**Calmar Ratio:** ${stats.calmarRatio === null ? "N/A" : `${stats.calmarRatio.toFixed(3)} (higher is better)`}`,
             `**Recovery Factor:** ${stats.recoveryFactor === null ? "N/A" : `${stats.recoveryFactor.toFixed(3)} (higher is better)`}`,
+            `**Expectancy:** ${stats.expectancy === null ? "N/A" : `${stats.expectancy > 0 ? "+" : ""}${stats.expectancy.toFixed(3)}% (higher is better)`}`,
             "",
             `*Win Rate: reliable above 200+ signals; below 30 signals a single streak can shift it by 10-20%.*`,
             `*Sharpe Ratio: below 1.0 is poor, 1.0-2.0 is acceptable, above 2.0 is strong. Requires 30+ signals.*`,
@@ -24910,6 +24927,7 @@ let ReportStorage$9 = class ReportStorage {
             `*Expected Yearly Returns: compounded geometric return from the equity curve, annualized by tradesPerYear. Same gating as Annualized Sharpe. Capped at ±${MAX_EXPECTED_YEARLY_RETURNS$1}% — values above the cap return N/A.*`,
             `*Calmar Ratio: below 0.5 is poor, 0.5-1.0 is acceptable, above 1.0 is strong. Denominator is compounded equity-curve max drawdown. Capped at ±${MAX_CALMAR_RATIO$1}.*`,
             `*Recovery Factor: below 1.0 means total profit does not cover max drawdown. Above 3.0 is considered good. Uses compounded total return as numerator.*`,
+            `*Expectancy: per-trade expected value (winProb × avgWin + lossProb × avgLoss). Positive = profitable on average per trade. Break-even trades contribute 0.*`,
             `*All metrics require 100+ signals to be statistically reliable. Annualized metrics assume the observed trading frequency and market conditions persist year-round.*`,
             `*IMPORTANT: Equity curve, Expected Yearly Returns, Calmar, Recovery and Max Drawdown all assume **100% capital allocation per trade** (no sizing, no portfolio fraction). Per-trade pnlPercentage is treated as a return on full equity. If your strategy risks X% of capital per trade, the realized portfolio return / drawdown will be roughly X/100 of the reported figures. The framework does not track portfolio-level sizing, so these metrics represent a theoretical upper bound under full allocation.*`,
             `*Negative values for Sharpe / Sortino / Calmar / Recovery / Expected Yearly Returns indicate a losing strategy (avgPnl < 0 or totalPnl < 0). "Higher is better" still applies — closer to zero is less bad, positive is profitable.*`,
@@ -27107,11 +27125,15 @@ class HeatmapStorage {
                 : null;
             portfolioTotalTrades = symbols.reduce((acc, s) => acc + s.totalTrades, 0);
         }
-        // Pooled Sharpe over all returns across symbols. NOTE: this is NOT a Markowitz
-        // portfolio Sharpe — it ignores cross-symbol correlations and treats trades as a
-        // single pooled sample. Gated by MIN_SIGNALS_FOR_RATIOS so a 2-trade pool cannot
-        // produce a noisy ±Sharpe.
+        // Pooled metrics over all returns across symbols. NOT a Markowitz portfolio —
+        // ignores cross-symbol correlations, treats trades as a single pooled sample.
+        // Gated by MIN_SIGNALS_FOR_RATIOS so a tiny pool can't produce noisy ratios.
         let portfolioSharpeRatio = null;
+        let portfolioStdDev = null;
+        let portfolioSortinoRatio = null;
+        let portfolioExpectancy = null;
+        let portfolioCalmarRatio = null;
+        let portfolioRecoveryFactor = null;
         const allReturns = [];
         for (const signals of this.symbolData.values()) {
             for (const s of signals) {
@@ -27122,10 +27144,63 @@ class HeatmapStorage {
             const portfolioAvg = allReturns.reduce((acc, r) => acc + r, 0) / allReturns.length;
             const portfolioVariance = allReturns.reduce((acc, r) => acc + Math.pow(r - portfolioAvg, 2), 0) /
                 (allReturns.length - 1);
-            const portfolioStdDev = Math.sqrt(portfolioVariance);
+            const stdDev = Math.sqrt(portfolioVariance);
             // STDDEV_EPSILON guard — same protection as per-symbol Sharpe.
-            if (portfolioStdDev > STDDEV_EPSILON) {
-                portfolioSharpeRatio = portfolioAvg / portfolioStdDev;
+            portfolioStdDev = stdDev;
+            if (stdDev > STDDEV_EPSILON) {
+                portfolioSharpeRatio = portfolioAvg / stdDev;
+            }
+            // Canonical Sortino: downside dev = √( Σ min(0, r)² / N_total ), MAR=0.
+            const negativeReturns = allReturns.filter((r) => r < 0);
+            if (negativeReturns.length > 0) {
+                const downsideVariance = negativeReturns.reduce((acc, r) => acc + r * r, 0) / allReturns.length;
+                const downsideDeviation = Math.sqrt(downsideVariance);
+                if (downsideDeviation > STDDEV_EPSILON) {
+                    portfolioSortinoRatio = portfolioAvg / downsideDeviation;
+                }
+            }
+            // Pooled Expectancy: per-trade EV = winProb*avgWin + lossProb*avgLoss.
+            // Break-even trades contribute 0 (excluded from both probs).
+            const wins = allReturns.filter((r) => r > 0);
+            const losses = allReturns.filter((r) => r < 0);
+            const total = allReturns.length;
+            const avgWin = wins.length > 0 ? wins.reduce((a, b) => a + b, 0) / wins.length : 0;
+            const avgLoss = losses.length > 0 ? losses.reduce((a, b) => a + b, 0) / losses.length : 0;
+            if (wins.length > 0 || losses.length > 0) {
+                portfolioExpectancy = (wins.length / total) * avgWin + (losses.length / total) * avgLoss;
+            }
+            // Pooled equity-curve max drawdown (compounded).
+            let equity = 1;
+            let peak = 1;
+            let maxDD = 0;
+            let blown = false;
+            for (const r of allReturns) {
+                equity *= 1 + r / 100;
+                if (equity <= 0) {
+                    maxDD = 100;
+                    blown = true;
+                    break;
+                }
+                if (equity > peak)
+                    peak = equity;
+                const dd = ((peak - equity) / peak) * 100;
+                if (dd > maxDD)
+                    maxDD = dd;
+            }
+            const equityFinal = blown ? 0 : equity;
+            // Pooled Calmar / Recovery, both clamped at ±MAX_CALMAR_RATIO and using
+            // compounded total return / DD. Same shape as per-symbol formula.
+            if (maxDD > 0) {
+                if (!blown) {
+                    const rawCalmar = ((equityFinal - 1) * 100) / maxDD;
+                    portfolioCalmarRatio = Math.max(-MAX_CALMAR_RATIO, Math.min(MAX_CALMAR_RATIO, rawCalmar));
+                    const rawRec = ((equityFinal - 1) * 100) / maxDD;
+                    portfolioRecoveryFactor = Math.max(-MAX_CALMAR_RATIO, Math.min(MAX_CALMAR_RATIO, rawRec));
+                }
+                else {
+                    // Blown — full loss is the only meaningful value; recovery undefined.
+                    portfolioCalmarRatio = -1; // -100 / 100
+                }
             }
         }
         // Portfolio-wide weighted average peak/fall PNL. Denominator must include only
@@ -27152,6 +27227,16 @@ class HeatmapStorage {
             portfolioAvgPeakPnl = null;
         if (isUnsafe(portfolioAvgFallPnl))
             portfolioAvgFallPnl = null;
+        if (isUnsafe(portfolioStdDev))
+            portfolioStdDev = null;
+        if (isUnsafe(portfolioSortinoRatio))
+            portfolioSortinoRatio = null;
+        if (isUnsafe(portfolioCalmarRatio))
+            portfolioCalmarRatio = null;
+        if (isUnsafe(portfolioRecoveryFactor))
+            portfolioRecoveryFactor = null;
+        if (isUnsafe(portfolioExpectancy))
+            portfolioExpectancy = null;
         return {
             symbols,
             totalSymbols,
@@ -27160,6 +27245,11 @@ class HeatmapStorage {
             portfolioTotalTrades,
             portfolioAvgPeakPnl,
             portfolioAvgFallPnl,
+            portfolioStdDev,
+            portfolioSortinoRatio,
+            portfolioCalmarRatio,
+            portfolioRecoveryFactor,
+            portfolioExpectancy,
         };
     }
     /**
@@ -27209,6 +27299,7 @@ class HeatmapStorage {
             `# Portfolio Heatmap: ${strategyName}`,
             "",
             `**Total Symbols:** ${data.totalSymbols} | **Portfolio PNL:** ${data.portfolioTotalPnl !== null ? str(data.portfolioTotalPnl, "%") : "N/A"} | **Pooled Sharpe:** ${data.portfolioSharpeRatio !== null ? str(data.portfolioSharpeRatio) : "N/A"} | **Total Trades:** ${data.portfolioTotalTrades} | **Avg Peak PNL:** ${data.portfolioAvgPeakPnl !== null ? str(data.portfolioAvgPeakPnl, "%") : "N/A"} | **Avg Max Drawdown PNL:** ${data.portfolioAvgFallPnl !== null ? str(data.portfolioAvgFallPnl, "%") : "N/A"}`,
+            `**Standard Deviation:** ${data.portfolioStdDev !== null ? str(data.portfolioStdDev, "%") : "N/A"} | **Sortino Ratio:** ${data.portfolioSortinoRatio !== null ? str(data.portfolioSortinoRatio) : "N/A"} | **Calmar Ratio:** ${data.portfolioCalmarRatio !== null ? str(data.portfolioCalmarRatio) : "N/A"} | **Recovery Factor:** ${data.portfolioRecoveryFactor !== null ? str(data.portfolioRecoveryFactor) : "N/A"} | **Expectancy:** ${data.portfolioExpectancy !== null ? str(data.portfolioExpectancy, "%") : "N/A"}`,
             "",
             table,
             "",
@@ -63839,6 +63930,34 @@ class CronUtils {
          * on successful settle.
          */
         this._firedOnce = new Set();
+        /**
+         * Last interval boundary already fired per periodic slot.
+         *
+         * Key shape (no `alignedMs` segment — one entry per logical slot, not per
+         * boundary; always carries the generation suffix `:g${generation}`, and the
+         * `:${symbol}` scope only in fan-out mode):
+         * - Periodic global: `${name}${genSuffix}`.
+         * - Periodic fan-out: `${name}:${symbol}${genSuffix}`.
+         *
+         * Value is the aligned-boundary epoch ms (`alignedMs`) most recently opened
+         * for that slot. `_tick` fires a periodic entry whenever the incoming tick's
+         * aligned boundary is **strictly greater** than the stored value, instead of
+         * requiring the tick to land *exactly* on the boundary. This fixes the
+         * dropped-boundary bug: when virtual time jumps over a boundary (e.g. a
+         * `5m`-driven loop skipping from 00:14 to 00:29 never lands on the `15m`
+         * 00:15 boundary), the old `ts === alignedMs` check silently lost the tick.
+         * With the watermark, the next tick whose `alignedMs` advanced past the
+         * stored value fires once for the newest crossed boundary (catch-up
+         * collapses multiple skipped boundaries into a single invocation at the
+         * latest one).
+         *
+         * 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`.
+         */
+        this._lastBoundary = new Map();
         /**
          * Register a periodic cron entry.
          *
@@ -63884,6 +64003,7 @@ class CronUtils {
                 }
             }
             this._clearFiredOnceFor(entry.name);
+            this._clearBoundaryFor(entry.name);
             const generation = ++this._generationCounter;
             this._entries.set(entry.name, { entry, generation });
             return () => this.unregister(entry.name);
@@ -63900,6 +64020,7 @@ class CronUtils {
             LOGGER_SERVICE$1.info(CRON_METHOD_NAME_UNREGISTER, { name });
             this._entries.delete(name);
             this._clearFiredOnceFor(name);
+            this._clearBoundaryFor(name);
         };
         /**
          * Clear fire-once marks so that fire-once entries can fire again.
@@ -63976,11 +64097,24 @@ class CronUtils {
          *    - Slot key: `${name}:once` (+ scope) (+ gen).
          *    - `aligned` = the 1-minute-aligned `when` from step 0.
          * 5. **Periodic** (`entry.interval` set):
-         *    - Align `when` further to the entry's interval via {@link alignToInterval}.
-         *    - If `ts !== alignedMs`, the tick is mid-interval — skip.
-         *      (This is the "remainder === 0" boundary check from the spec;
-         *      since `ts` is already on the 1-minute boundary, the check is exact
-         *      for `1m` and consistent for higher intervals.)
+         *    - Align `when` to the entry's interval via {@link alignToInterval} to
+         *      get `alignedMs`, the boundary this tick belongs to.
+         *    - Compare against the slot's watermark in `_lastBoundary` (keyed by
+         *      `${name}` + scope + gen, without the `alignedMs` segment). If a
+         *      watermark exists and `alignedMs <= lastBoundary`, this boundary was
+         *      already fired — skip.
+         *    - This **watermark** check replaces the old exact `ts === alignedMs`
+         *      match. The exact match required virtual time to land *precisely* on
+         *      the boundary; when a tick jumped clean over a boundary (e.g. a `5m`
+         *      loop going 00:14 → 00:29 never touching the `15m` 00:15 boundary)
+         *      the boundary was silently lost. With the watermark, the first tick
+         *      whose `alignedMs` advanced past the stored value fires once, at the
+         *      newest crossed boundary (catch-up collapses several skipped
+         *      boundaries into a single invocation at the latest one).
+         *    - The watermark is advanced to `alignedMs` synchronously when the slot
+         *      is opened (before the `await`), so a concurrent tick on the same or
+         *      an already-passed boundary cannot open a duplicate slot while the
+         *      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
@@ -64029,6 +64163,9 @@ class CronUtils {
                 let alignedMs;
                 let slotKey;
                 let firedKey;
+                // Periodic-only watermark key (no `alignedMs` segment); null for
+                // fire-once entries, which coordinate via `_firedOnce` instead.
+                let boundaryKey;
                 if (entry.interval === undefined) {
                     const onceKey = `${entry.name}${scope}${genSuffix}`;
                     if (this._firedOnce.has(onceKey)) {
@@ -64038,11 +64175,18 @@ class CronUtils {
                     alignedMs = ts;
                     slotKey = `${entry.name}:once${scope}${genSuffix}`;
                     firedKey = onceKey;
+                    boundaryKey = null;
                 }
                 else {
                     aligned = alignToInterval(when, entry.interval);
                     alignedMs = aligned.getTime();
-                    if (ts !== alignedMs) {
+                    boundaryKey = `${entry.name}${scope}${genSuffix}`;
+                    const lastBoundary = this._lastBoundary.get(boundaryKey);
+                    // Fire when the tick's aligned boundary has advanced past the last one
+                    // we fired for this slot. Using `>` instead of the old `ts === alignedMs`
+                    // means a virtual-time jump that skips clean over a boundary still
+                    // fires once, at the newest crossed boundary, rather than dropping it.
+                    if (lastBoundary !== undefined && alignedMs <= lastBoundary) {
                         continue;
                     }
                     slotKey = `${entry.name}:${alignedMs}${scope}${genSuffix}`;
@@ -64050,6 +64194,13 @@ class CronUtils {
                 }
                 let pending = this._inFlight.get(slotKey);
                 if (!pending) {
+                    // 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.
+                    if (boundaryKey !== null) {
+                        this._lastBoundary.set(boundaryKey, alignedMs);
+                    }
                     pending = this._runEntry(entry, symbol, aligned, alignedMs, slotKey, firedKey, backtest);
                     this._inFlight.set(slotKey, pending);
                 }
@@ -64141,7 +64292,10 @@ class CronUtils {
          * 3. Wipes `_firedOnce` — all fire-once marks are dropped, so any future
          *    re-registration of the same `name` fires again on the next matching
          *    tick.
-         * 4. Does **not** touch `_inFlight` — in-flight handlers continue to
+         * 4. Wipes `_lastBoundary` — all periodic watermarks are dropped, so a
+         *    re-registered periodic entry starts firing from its next crossed
+         *    boundary again.
+         * 5. Does **not** touch `_inFlight` — in-flight handlers continue to
          *    settle in the background and clear their own slots via `.finally()`.
          *    Their final `_firedOnce.add(firedKey)` writes carry old-generation
          *    keys and are harmless (lookup uses the post-dispose generation).
@@ -64160,8 +64314,29 @@ class CronUtils {
             this.disable();
             this._entries.clear();
             this._firedOnce.clear();
+            this._lastBoundary.clear();
         };
     }
+    /**
+     * Garbage-collect every `_lastBoundary` key that belongs to the entry `name`
+     * (any generation, global or fan-out).
+     *
+     * Called from `register`/`unregister` alongside `_clearFiredOnceFor`. Like
+     * that helper this is memory hygiene, not correctness — the generation suffix
+     * already isolates re-registrations, so a stale watermark from an old
+     * generation can never gate a new entry.
+     */
+    _clearBoundaryFor(name) {
+        if (!name) {
+            return;
+        }
+        const prefix = `${name}:`;
+        for (const key of this._lastBoundary.keys()) {
+            if (key === name || key.startsWith(prefix)) {
+                this._lastBoundary.delete(key);
+            }
+        }
+    }
     /**
      * Garbage-collect every `_firedOnce` key that belongs to the entry `name`
      * (any generation, global or fan-out).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backtest-kit",
-  "version": "11.0.0",
+  "version": "11.3.0",
   "description": "A TypeScript library for trading system backtest",
   "author": {
     "name": "Petr Tripolsky",

package/types.d.ts

@@ -4634,6 +4634,8 @@ interface BacktestStatisticsModel {
     calmarRatio: number | null;
     /** Recovery Factor (totalPnl / max drawdown), null if unsafe. Higher is better. */
     recoveryFactor: number | null;
+    /** Per-trade Expectancy (winProb*avgWin + lossProb*avgLoss), null if unsafe. Higher is better. */
+    expectancy: number | null;
 }
 
 /**
@@ -12609,6 +12611,8 @@ interface LiveStatisticsModel {
     calmarRatio: number | null;
     /** Recovery Factor (totalPnl / max drawdown), null if unsafe. Higher is better. */
     recoveryFactor: number | null;
+    /** Per-trade Expectancy (winProb*avgWin + lossProb*avgLoss), null if unsafe. Higher is better. */
+    expectancy: number | null;
 }
 
 /**
@@ -12630,6 +12634,16 @@ interface HeatmapStatisticsModel {
     portfolioAvgPeakPnl: number | null;
     /** Trade-count-weighted average fall PNL across all symbols. Closer to 0 is better. */
     portfolioAvgFallPnl: number | null;
+    /** Pooled sample standard deviation of returns across all symbols. */
+    portfolioStdDev: number | null;
+    /** Pooled Sortino Ratio over all trades. Same canonical formula as per-symbol. */
+    portfolioSortinoRatio: number | null;
+    /** Pooled Calmar Ratio: pooled compound annual / equity drawdown. Capped at ±MAX_CALMAR_RATIO. */
+    portfolioCalmarRatio: number | null;
+    /** Pooled Recovery Factor: (equityFinal-1)*100 / equityMaxDrawdown. Capped at ±MAX_CALMAR_RATIO. */
+    portfolioRecoveryFactor: number | null;
+    /** Pooled Expectancy: winProb*avgWin + lossProb*avgLoss (per-trade expected %). */
+    portfolioExpectancy: number | null;
 }
 
 /**
@@ -26322,6 +26336,44 @@ declare class CronUtils {
      * on successful settle.
      */
     private readonly _firedOnce;
+    /**
+     * Last interval boundary already fired per periodic slot.
+     *
+     * Key shape (no `alignedMs` segment — one entry per logical slot, not per
+     * boundary; always carries the generation suffix `:g${generation}`, and the
+     * `:${symbol}` scope only in fan-out mode):
+     * - Periodic global: `${name}${genSuffix}`.
+     * - Periodic fan-out: `${name}:${symbol}${genSuffix}`.
+     *
+     * Value is the aligned-boundary epoch ms (`alignedMs`) most recently opened
+     * for that slot. `_tick` fires a periodic entry whenever the incoming tick's
+     * aligned boundary is **strictly greater** than the stored value, instead of
+     * requiring the tick to land *exactly* on the boundary. This fixes the
+     * dropped-boundary bug: when virtual time jumps over a boundary (e.g. a
+     * `5m`-driven loop skipping from 00:14 to 00:29 never lands on the `15m`
+     * 00:15 boundary), the old `ts === alignedMs` check silently lost the tick.
+     * With the watermark, the next tick whose `alignedMs` advanced past the
+     * stored value fires once for the newest crossed boundary (catch-up
+     * collapses multiple skipped boundaries into a single invocation at the
+     * latest one).
+     *
+     * 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`.
+     */
+    private readonly _lastBoundary;
+    /**
+     * Garbage-collect every `_lastBoundary` key that belongs to the entry `name`
+     * (any generation, global or fan-out).
+     *
+     * Called from `register`/`unregister` alongside `_clearFiredOnceFor`. Like
+     * that helper this is memory hygiene, not correctness — the generation suffix
+     * already isolates re-registrations, so a stale watermark from an old
+     * generation can never gate a new entry.
+     */
+    private _clearBoundaryFor;
     /**
      * Garbage-collect every `_firedOnce` key that belongs to the entry `name`
      * (any generation, global or fan-out).
@@ -26443,11 +26495,24 @@ declare class CronUtils {
      *    - Slot key: `${name}:once` (+ scope) (+ gen).
      *    - `aligned` = the 1-minute-aligned `when` from step 0.
      * 5. **Periodic** (`entry.interval` set):
-     *    - Align `when` further to the entry's interval via {@link alignToInterval}.
-     *    - If `ts !== alignedMs`, the tick is mid-interval — skip.
-     *      (This is the "remainder === 0" boundary check from the spec;
-     *      since `ts` is already on the 1-minute boundary, the check is exact
-     *      for `1m` and consistent for higher intervals.)
+     *    - Align `when` to the entry's interval via {@link alignToInterval} to
+     *      get `alignedMs`, the boundary this tick belongs to.
+     *    - Compare against the slot's watermark in `_lastBoundary` (keyed by
+     *      `${name}` + scope + gen, without the `alignedMs` segment). If a
+     *      watermark exists and `alignedMs <= lastBoundary`, this boundary was
+     *      already fired — skip.
+     *    - This **watermark** check replaces the old exact `ts === alignedMs`
+     *      match. The exact match required virtual time to land *precisely* on
+     *      the boundary; when a tick jumped clean over a boundary (e.g. a `5m`
+     *      loop going 00:14 → 00:29 never touching the `15m` 00:15 boundary)
+     *      the boundary was silently lost. With the watermark, the first tick
+     *      whose `alignedMs` advanced past the stored value fires once, at the
+     *      newest crossed boundary (catch-up collapses several skipped
+     *      boundaries into a single invocation at the latest one).
+     *    - The watermark is advanced to `alignedMs` synchronously when the slot
+     *      is opened (before the `await`), so a concurrent tick on the same or
+     *      an already-passed boundary cannot open a duplicate slot while the
+     *      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
@@ -26541,7 +26606,10 @@ declare class CronUtils {
      * 3. Wipes `_firedOnce` — all fire-once marks are dropped, so any future
      *    re-registration of the same `name` fires again on the next matching
      *    tick.
-     * 4. Does **not** touch `_inFlight` — in-flight handlers continue to
+     * 4. Wipes `_lastBoundary` — all periodic watermarks are dropped, so a
+     *    re-registered periodic entry starts firing from its next crossed
+     *    boundary again.
+     * 5. Does **not** touch `_inFlight` — in-flight handlers continue to
      *    settle in the background and clear their own slots via `.finally()`.
      *    Their final `_firedOnce.add(firedKey)` writes carry old-generation
      *    keys and are harmless (lookup uses the post-dispose generation).