backtest-kit 11.2.0 → 11.4.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,
             "",

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,
             "",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backtest-kit",
-  "version": "11.2.0",
+  "version": "11.4.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;
 }
 
 /**