backtest-kit 11.4.0 → 11.5.2

package/build/index.mjs

@@ -23865,13 +23865,34 @@ let ReportStorage$a = class ReportStorage {
         // per trade ("as-if 100% allocation"). Walks validSignals in chronological order
         // (storage is newest-first, so iterate in reverse). Using validSignals (same set as
         // tradesPerYear) keeps equityFinal consistent with the annualization exponent.
-        // If equity goes ≤ 0 (e.g. leveraged short with r < -100%) — account blown,
-        // fix DD at 100% and stop walking the curve.
+        //
+        // MARK-TO-MARKET DD: each trade's worst intra-trade excursion (signal.maxDrawdown,
+        // i.e. the `_fall` snapshot, ≤ 0) is applied as a trough BEFORE booking the realized
+        // close. Without this the curve only steps at close, so a trade that dipped to -18%
+        // and recovered to +2% would register zero drawdown — understating DD and inflating
+        // Calmar/Recovery. The trough does not persist into equity (it's a transient
+        // mark-to-market low); equity then moves to the realized close.
+        // If equity (at trough or close) goes ≤ 0 (e.g. leveraged loss < -100%) — account
+        // blown, fix DD at 100% and stop walking the curve.
         let equity = 1;
         let peak = 1;
         let equityMaxDrawdown = 0;
         let blown = false;
         for (let i = validSignals.length - 1; i >= 0; i--) {
+            // Intra-trade trough — mark-to-market low while the position was open.
+            const fallPct = validSignals[i].signal.maxDrawdown?.pnlPercentage;
+            if (typeof fallPct === "number" && fallPct < 0) {
+                const trough = equity * (1 + fallPct / 100);
+                if (trough <= 0) {
+                    equityMaxDrawdown = 100;
+                    blown = true;
+                    break;
+                }
+                const troughDd = (peak - trough) / peak * 100;
+                if (troughDd > equityMaxDrawdown)
+                    equityMaxDrawdown = troughDd;
+            }
+            // Realized close — book the final per-trade result.
             equity *= 1 + validSignals[i].pnl.pnlPercentage / 100;
             if (equity <= 0) {
                 equityMaxDrawdown = 100;
@@ -24029,7 +24050,7 @@ let ReportStorage$a = class ReportStorage {
             `**Win rate:** ${stats.winRate === null ? "N/A" : `${stats.winRate.toFixed(2)}% (${stats.winCount}W / ${stats.lossCount}L) (higher is better)`}`,
             `**Average PNL:** ${stats.avgPnl === null ? "N/A" : `${stats.avgPnl > 0 ? "+" : ""}${stats.avgPnl.toFixed(2)}% (higher is better)`}`,
             `**Total PNL:** ${stats.totalPnl === null ? "N/A" : `${stats.totalPnl > 0 ? "+" : ""}${stats.totalPnl.toFixed(2)}% (higher is better)`}`,
-            `**Standard Deviation:** ${stats.stdDev === null ? "N/A" : `${stats.stdDev.toFixed(3)}% (lower is better)`}`,
+            `**Standard Deviation Per Trade:** ${stats.stdDev === null ? "N/A" : `${stats.stdDev.toFixed(3)}% (lower is better)`}`,
             `**Sharpe Ratio:** ${stats.sharpeRatio === null ? "N/A" : `${stats.sharpeRatio.toFixed(3)} (higher is better)`}`,
             `**Annualized Sharpe Ratio:** ${stats.annualizedSharpeRatio === null ? "N/A" : `${stats.annualizedSharpeRatio.toFixed(3)} (higher is better)`}`,
             `**Certainty Ratio:** ${stats.certaintyRatio === null ? "N/A" : `${stats.certaintyRatio.toFixed(3)} (higher is better)`}`,
@@ -24047,11 +24068,12 @@ let ReportStorage$a = class ReportStorage {
             `*Sortino Ratio: below 1.0 is poor, 1.0-2.0 is acceptable, above 2.0 is strong. Requires 30+ signals. N/A when no losing trades — Sortino is mathematically undefined (infinite) and we cannot distinguish "truly flawless" from "lucky streak so far".*`,
             `*Certainty Ratio: below 1.0 means average loss exceeds average win. Above 1.5 is considered good.*`,
             `*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.*`,
+            `*Calmar Ratio: below 0.5 is poor, 0.5-1.0 is acceptable, above 1.0 is strong. Denominator is the mark-to-market max drawdown (see below). 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 and the mark-to-market max drawdown as denominator.*`,
+            `*Max Drawdown: mark-to-market — the compounded equity curve applies each trade's worst intra-trade excursion (the lowest unrealized point while the position was open) before booking its realized close, so deep round-trip dips count. It is NOT realized-only (close-to-close); a realized-only curve would understate drawdown and inflate Calmar/Recovery.*`,
             `*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.*`,
+            `*IMPORTANT: Equity curve, Expected Yearly Returns, Calmar, Recovery and Max Drawdown all assume **100% capital allocation per position** (no portfolio fraction). These metrics ignore the position-sizing subsystem (PositionSize / Kelly / ATR): pnlPercentage is a return on the position's own invested capital, never scaled by account balance. With DCA (commitAverageBuy) the cost basis is the sum of all entries and the entry price is dollar-cost-weighted, so per-trade % is measured against the averaged position, not a fixed stake. If your strategy risks X% of capital per trade, the realized portfolio return / drawdown will be roughly X/100 of the reported figures — these metrics represent a theoretical upper bound under full allocation.*`,
             `*Negative values for Sharpe / 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.*`,
         ].join("\n");
     }
@@ -24800,15 +24822,37 @@ let ReportStorage$9 = class ReportStorage {
         // on cost basis — compounding assumes equal capital allocation per trade ("as-if 100%").
         // If equity ≤ 0 (leveraged short with r < -100%) — account blown, fix DD at 100%.
         // Built from validClosed (newest-first), iterated reverse for chronological order.
-        const chronologicalReturns = [];
+        //
+        // MARK-TO-MARKET DD: each trade's worst intra-trade excursion (fallPnl, the `_fall`
+        // snapshot, ≤ 0) is applied as a trough BEFORE booking the realized close. Without it
+        // the curve only steps at close, so a trade that dipped to -18% and recovered to +2%
+        // would register zero drawdown — understating DD and inflating Calmar/Recovery.
+        const chronological = [];
         for (let i = validClosed.length - 1; i >= 0; i--) {
-            chronologicalReturns.push(validClosed[i].pnl);
+            const fall = validClosed[i].fallPnl;
+            chronological.push({
+                r: validClosed[i].pnl,
+                fall: typeof fall === "number" ? fall : null,
+            });
         }
         let equity = 1;
         let peak = 1;
         let equityMaxDrawdown = 0;
         let blown = false;
-        for (const r of chronologicalReturns) {
+        for (const { r, fall } of chronological) {
+            // Intra-trade trough — mark-to-market low while the position was open.
+            if (fall !== null && fall < 0) {
+                const trough = equity * (1 + fall / 100);
+                if (trough <= 0) {
+                    equityMaxDrawdown = 100;
+                    blown = true;
+                    break;
+                }
+                const troughDd = (peak - trough) / peak * 100;
+                if (troughDd > equityMaxDrawdown)
+                    equityMaxDrawdown = troughDd;
+            }
+            // Realized close.
             equity *= 1 + r / 100;
             if (equity <= 0) {
                 equityMaxDrawdown = 100;
@@ -24907,7 +24951,7 @@ let ReportStorage$9 = class ReportStorage {
             `**Win rate:** ${stats.winRate === null ? "N/A" : `${stats.winRate.toFixed(2)}% (${stats.winCount}W / ${stats.lossCount}L) (higher is better)`}`,
             `**Average PNL:** ${stats.avgPnl === null ? "N/A" : `${stats.avgPnl > 0 ? "+" : ""}${stats.avgPnl.toFixed(2)}% (higher is better)`}`,
             `**Total PNL:** ${stats.totalPnl === null ? "N/A" : `${stats.totalPnl > 0 ? "+" : ""}${stats.totalPnl.toFixed(2)}% (higher is better)`}`,
-            `**Standard Deviation:** ${stats.stdDev === null ? "N/A" : `${stats.stdDev.toFixed(3)}% (lower is better)`}`,
+            `**Standard Deviation Per Trade:** ${stats.stdDev === null ? "N/A" : `${stats.stdDev.toFixed(3)}% (lower is better)`}`,
             `**Sharpe Ratio:** ${stats.sharpeRatio === null ? "N/A" : `${stats.sharpeRatio.toFixed(3)} (higher is better)`}`,
             `**Annualized Sharpe Ratio:** ${stats.annualizedSharpeRatio === null ? "N/A" : `${stats.annualizedSharpeRatio.toFixed(3)} (higher is better)`}`,
             `**Certainty Ratio:** ${stats.certaintyRatio === null ? "N/A" : `${stats.certaintyRatio.toFixed(3)} (higher is better)`}`,
@@ -24925,11 +24969,12 @@ let ReportStorage$9 = class ReportStorage {
             `*Sortino Ratio: below 1.0 is poor, 1.0-2.0 is acceptable, above 2.0 is strong. Requires 30+ signals. N/A when no losing trades — Sortino is mathematically undefined (infinite) and we cannot distinguish "truly flawless" from "lucky streak so far".*`,
             `*Certainty Ratio: below 1.0 means average loss exceeds average win. Above 1.5 is considered good.*`,
             `*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.*`,
+            `*Calmar Ratio: below 0.5 is poor, 0.5-1.0 is acceptable, above 1.0 is strong. Denominator is the mark-to-market max drawdown (see below). 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 and the mark-to-market max drawdown as denominator.*`,
+            `*Max Drawdown: mark-to-market — the compounded equity curve applies each trade's worst intra-trade excursion (the lowest unrealized point while the position was open) before booking its realized close, so deep round-trip dips count. It is NOT realized-only (close-to-close); a realized-only curve would understate drawdown and inflate Calmar/Recovery.*`,
             `*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.*`,
+            `*IMPORTANT: Equity curve, Expected Yearly Returns, Calmar, Recovery and Max Drawdown all assume **100% capital allocation per position** (no portfolio fraction). These metrics ignore the position-sizing subsystem (PositionSize / Kelly / ATR): pnlPercentage is a return on the position's own invested capital, never scaled by account balance. With DCA (commitAverageBuy) the cost basis is the sum of all entries and the entry price is dollar-cost-weighted, so per-trade % is measured against the averaged position, not a fixed stake. If your strategy risks X% of capital per trade, the realized portfolio return / drawdown will be roughly X/100 of the reported figures — these metrics represent a theoretical upper bound under full allocation.*`,
             `*Negative values for Sharpe / 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.*`,
         ].join("\n");
     }
@@ -26841,6 +26886,12 @@ class HeatmapStorage {
         // Equity-curve max drawdown via compounded equity ("as-if 100% allocation per trade").
         // Signals are stored newest-first (unshift in addSignal), so iterate in reverse.
         // If equity ≤ 0 — account blown, fix DD at 100%. equityFinal feeds expectedYearlyReturns.
+        //
+        // MARK-TO-MARKET DD: each trade's worst intra-trade excursion (signal.maxDrawdown,
+        // the `_fall` snapshot, ≤ 0) is applied as a trough BEFORE booking the realized close.
+        // Without it the curve only steps at close, so a trade that dipped to -18% and
+        // recovered to +2% would register zero drawdown — understating DD and inflating
+        // Calmar/Recovery.
         let maxDrawdown = null;
         let equityFinal = 1;
         let blown = false;
@@ -26849,6 +26900,18 @@ class HeatmapStorage {
             let peak = 1;
             let maxDD = 0;
             for (let i = signals.length - 1; i >= 0; i--) {
+                const fallPct = signals[i].signal.maxDrawdown?.pnlPercentage;
+                if (typeof fallPct === "number" && fallPct < 0) {
+                    const trough = equity * (1 + fallPct / 100);
+                    if (trough <= 0) {
+                        maxDD = 100;
+                        blown = true;
+                        break;
+                    }
+                    const troughDd = (peak - trough) / peak * 100;
+                    if (troughDd > maxDD)
+                        maxDD = troughDd;
+                }
                 equity *= 1 + signals[i].pnl.pnlPercentage / 100;
                 if (equity <= 0) {
                     maxDD = 100;
@@ -27135,9 +27198,20 @@ class HeatmapStorage {
         let portfolioCalmarRatio = null;
         let portfolioRecoveryFactor = null;
         const allReturns = [];
+        // Parallel array of intra-trade troughs (≤ 0), aligned 1:1 with allReturns,
+        // used for mark-to-market DD in the pooled equity curve below.
+        const allFalls = [];
+        let poolFirstPendingAt = Infinity;
+        let poolLastCloseAt = -Infinity;
         for (const signals of this.symbolData.values()) {
             for (const s of signals) {
                 allReturns.push(s.pnl.pnlPercentage);
+                const fall = s.signal.maxDrawdown?.pnlPercentage;
+                allFalls.push(typeof fall === "number" ? fall : null);
+                if (s.signal.pendingAt < poolFirstPendingAt)
+                    poolFirstPendingAt = s.signal.pendingAt;
+                if (s.closeTimestamp > poolLastCloseAt)
+                    poolLastCloseAt = s.closeTimestamp;
             }
         }
         if (allReturns.length >= MIN_SIGNALS_FOR_RATIOS) {
@@ -27169,13 +27243,27 @@ class HeatmapStorage {
             if (wins.length > 0 || losses.length > 0) {
                 portfolioExpectancy = (wins.length / total) * avgWin + (losses.length / total) * avgLoss;
             }
-            // Pooled equity-curve max drawdown (compounded).
+            // Pooled equity-curve max drawdown (compounded). MARK-TO-MARKET: each trade's
+            // intra-trade trough (allFalls, ≤ 0) is applied before booking the realized close,
+            // so deep round-trip dips are captured rather than understating DD.
             let equity = 1;
             let peak = 1;
             let maxDD = 0;
             let blown = false;
-            for (const r of allReturns) {
-                equity *= 1 + r / 100;
+            for (let i = 0; i < allReturns.length; i++) {
+                const fall = allFalls[i];
+                if (fall !== null && fall < 0) {
+                    const trough = equity * (1 + fall / 100);
+                    if (trough <= 0) {
+                        maxDD = 100;
+                        blown = true;
+                        break;
+                    }
+                    const troughDd = ((peak - trough) / peak) * 100;
+                    if (troughDd > maxDD)
+                        maxDD = troughDd;
+                }
+                equity *= 1 + allReturns[i] / 100;
                 if (equity <= 0) {
                     maxDD = 100;
                     blown = true;
@@ -27188,20 +27276,43 @@ class HeatmapStorage {
                     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
+            // Pooled expected yearly returns — geometric annualization of the pooled
+            // equity curve, gated exactly like the per-symbol path: requires a valid
+            // calendar span (≥ MIN_CALENDAR_SPAN_DAYS) and a non-clustered trade
+            // frequency (≤ MAX_TRADES_PER_YEAR). Above MAX_EXPECTED_YEARLY_RETURNS → null
+            // (don't surface the cap as a real figure). This is the numerator for Calmar.
+            let pooledExpectedYearlyReturns = null;
+            const poolSpanDays = isFinite(poolFirstPendingAt) && isFinite(poolLastCloseAt)
+                ? (poolLastCloseAt - poolFirstPendingAt) / (1000 * 60 * 60 * 24)
+                : 0;
+            if (poolSpanDays >= MIN_CALENDAR_SPAN_DAYS) {
+                const rawTradesPerYear = (allReturns.length / poolSpanDays) * 365;
+                if (rawTradesPerYear <= MAX_TRADES_PER_YEAR) {
+                    if (blown) {
+                        pooledExpectedYearlyReturns = -100;
+                    }
+                    else {
+                        const raw = (Math.pow(equityFinal, rawTradesPerYear / allReturns.length) - 1) * 100;
+                        pooledExpectedYearlyReturns =
+                            Math.abs(raw) > MAX_EXPECTED_YEARLY_RETURNS ? null : raw;
+                    }
                 }
             }
+            // Pooled Calmar = annualized return / max drawdown — same formula and
+            // gating as per-symbol Calmar. NULL when the annualized numerator is
+            // unavailable (span/frequency gate, or over the yearly cap). This is what
+            // distinguishes it from Recovery, which uses the compounded TOTAL return —
+            // previously both used total return, making Calmar == Recovery (a bug).
+            if (maxDD > 0 && pooledExpectedYearlyReturns !== null) {
+                portfolioCalmarRatio = Math.max(-MAX_CALMAR_RATIO, Math.min(MAX_CALMAR_RATIO, pooledExpectedYearlyReturns / maxDD));
+            }
+            // Pooled Recovery Factor = compounded TOTAL return / max drawdown, clamped.
+            // Time-independent (no annualization), so it needs no span gate — only a
+            // valid DD and a non-blown account (ratio is meaningless after total loss).
+            if (maxDD > 0 && !blown) {
+                const rawRec = ((equityFinal - 1) * 100) / maxDD;
+                portfolioRecoveryFactor = Math.max(-MAX_CALMAR_RATIO, Math.min(MAX_CALMAR_RATIO, rawRec));
+            }
         }
         // Portfolio-wide weighted average peak/fall PNL. Denominator must include only
         // symbols that contributed a value — otherwise trade-count-weighted mean is diluted
@@ -27298,8 +27409,17 @@ class HeatmapStorage {
         return [
             `# 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"}`,
+            `**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 Per Trade:** ${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,
             "",
@@ -27309,10 +27429,11 @@ class HeatmapStorage {
             `*Sortino Ratio: below 1.0 is poor, 1.0-2.0 is acceptable, above 2.0 is strong. Requires 30+ signals. N/A when no losing trades — Sortino is mathematically undefined (infinite) and we cannot distinguish "truly flawless" from "lucky streak so far".*`,
             `*Certainty Ratio: below 1.0 means average loss exceeds average win. Above 1.5 is considered good.*`,
             `*Profit Factor: below 1.0 means strategy is losing overall. Above 1.5 is considered good.*`,
-            `*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. N/A unless ≥${MIN_SIGNALS_FOR_ANNUALIZATION} signals per symbol and span ≥${MIN_CALENDAR_SPAN_DAYS} days. Capped at ±${MAX_CALMAR_RATIO}.*`,
-            `*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.*`,
+            `*Calmar Ratio: below 0.5 is poor, 0.5-1.0 is acceptable, above 1.0 is strong. Denominator is the mark-to-market max drawdown (see below). N/A unless ≥${MIN_SIGNALS_FOR_ANNUALIZATION} signals per symbol and span ≥${MIN_CALENDAR_SPAN_DAYS} days. Capped at ±${MAX_CALMAR_RATIO}.*`,
+            `*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 and the mark-to-market max drawdown as denominator.*`,
+            `*Max Drawdown: mark-to-market — both the per-symbol and pooled equity curves apply each trade's worst intra-trade excursion (the lowest unrealized point while the position was open) before booking its realized close, so deep round-trip dips count. It is NOT realized-only (close-to-close); a realized-only curve would understate drawdown and inflate Calmar/Recovery. NOTE: the pooled curve orders trades by storage sequence, not wall-clock time, so simultaneous cross-symbol drawdowns are not modelled.*`,
             `*All metrics require 100+ signals per symbol to be statistically reliable. Annualized metrics assume the observed trading frequency persists year-round.*`,
-            `*IMPORTANT: Per-symbol equity curve, Expected Yearly Returns, Calmar, Recovery and Max Drawdown all assume **100% capital allocation per trade** (no sizing, no portfolio fraction). If your strategy risks X% of capital per trade, the realized 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.*`,
+            `*IMPORTANT: Per-symbol equity curve, Expected Yearly Returns, Calmar, Recovery and Max Drawdown all assume **100% capital allocation per position** (no portfolio fraction). These metrics ignore the position-sizing subsystem (PositionSize / Kelly / ATR): pnlPercentage is a return on the position's own invested capital, never scaled by account balance. With DCA (commitAverageBuy) the cost basis is the sum of all entries and the entry price is dollar-cost-weighted, so per-trade % is measured against the averaged position, not a fixed stake. If your strategy risks X% of capital per trade, the realized return / drawdown will be roughly X/100 of the reported figures — these metrics represent a theoretical upper bound under full allocation.*`,
             `*Negative values for Sharpe / Sortino / Calmar / Recovery indicate a losing symbol (avgPnl < 0 or totalPnl < 0). "Higher is better" still applies — closer to zero is less bad, positive is profitable.*`,
         ].join("\n");
     }

package/package.json

@@ -1,86 +1,86 @@
-{
-  "name": "backtest-kit",
-  "version": "11.4.0",
-  "description": "A TypeScript library for trading system backtest",
-  "author": {
-    "name": "Petr Tripolsky",
-    "email": "tripolskypetr@gmail.com",
-    "url": "https://github.com/tripolskypetr"
-  },
-  "funding": {
-    "type": "individual",
-    "url": "http://paypal.me/tripolskypetr"
-  },
-  "license": "MIT",
-  "homepage": "https://backtest-kit.github.io/documents/article_07_ai_news_trading_signals.html",
-  "keywords": [
-    "backtesting",
-    "backtest",
-    "finance",
-    "trading",
-    "candles",
-    "indicators",
-    "multi value",
-    "multi symbol",
-    "framework"
-  ],
-  "files": [
-    "build",
-    "types.d.ts",
-    "README.md"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/tripolskypetr/backtest-kit",
-    "documentation": "https://github.com/tripolskypetr/backtest-kit/tree/master/docs"
-  },
-  "bugs": {
-    "url": "https://github.com/tripolskypetr/backtest-kit/issues"
-  },
-  "scripts": {
-    "build": "rollup -c",
-    "test": "npm run build && node ./test/index.mjs",
-    "build:docs": "rimraf docs && mkdir docs && node ./scripts/dts-docs.cjs ./types.d.ts ./docs",
-    "docs:gpt": "npm run build && node ./tools/gpt-docs/index.mjs",
-    "docs:uml": "npm run build && node ./scripts/uml.mjs",
-    "docs:www": "rimraf docs/wwwroot && node ./tools/typedoc-packages-docs/index.mjs && typedoc && node ./tools/typedoc-yandex-metrica/index.mjs",
-    "repl": "dotenv -e .env -- npm run build && node -e \"import('./scripts/repl.mjs')\" --interactive"
-  },
-  "main": "build/index.cjs",
-  "module": "build/index.mjs",
-  "source": "src/index.ts",
-  "types": "./types.d.ts",
-  "exports": {
-    "require": "./build/index.cjs",
-    "types": "./types.d.ts",
-    "import": "./build/index.mjs",
-    "default": "./build/index.cjs"
-  },
-  "devDependencies": {
-    "@rollup/plugin-typescript": "11.1.6",
-    "@types/node": "22.9.0",
-    "glob": "11.0.1",
-    "plantuml": "0.0.2",
-    "rimraf": "6.0.1",
-    "rollup": "3.29.5",
-    "rollup-plugin-dts": "6.1.1",
-    "rollup-plugin-peer-deps-external": "2.2.4",
-    "ts-morph": "27.0.2",
-    "tslib": "2.7.0",
-    "typedoc": "0.27.9",
-    "worker-testbed": "2.0.0"
-  },
-  "peerDependencies": {
-    "typescript": "^5.0.0"
-  },
-  "dependencies": {
-    "di-kit": "^1.1.1",
-    "di-scoped": "^1.0.21",
-    "di-singleton": "^1.0.5",
-    "functools-kit": "^2.3.0",
-    "get-moment-stamp": "^2.0.0"
-  },
-  "publishConfig": {
-    "access": "public"
-  }
-}
+{
+  "name": "backtest-kit",
+  "version": "11.5.2",
+  "description": "A TypeScript library for trading system backtest",
+  "author": {
+    "name": "Petr Tripolsky",
+    "email": "tripolskypetr@gmail.com",
+    "url": "https://github.com/tripolskypetr"
+  },
+  "funding": {
+    "type": "individual",
+    "url": "http://paypal.me/tripolskypetr"
+  },
+  "license": "MIT",
+  "homepage": "https://backtest-kit.github.io/documents/article_07_ai_news_trading_signals.html",
+  "keywords": [
+    "backtesting",
+    "backtest",
+    "finance",
+    "trading",
+    "candles",
+    "indicators",
+    "multi value",
+    "multi symbol",
+    "framework"
+  ],
+  "files": [
+    "build",
+    "types.d.ts",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tripolskypetr/backtest-kit",
+    "documentation": "https://github.com/tripolskypetr/backtest-kit/tree/master/docs"
+  },
+  "bugs": {
+    "url": "https://github.com/tripolskypetr/backtest-kit/issues"
+  },
+  "scripts": {
+    "build": "rollup -c",
+    "test": "npm run build && node ./test/index.mjs",
+    "build:docs": "rimraf docs && mkdir docs && node ./scripts/dts-docs.cjs ./types.d.ts ./docs",
+    "docs:gpt": "npm run build && node ./tools/gpt-docs/index.mjs",
+    "docs:uml": "npm run build && node ./scripts/uml.mjs",
+    "docs:www": "rimraf docs/wwwroot && node ./tools/typedoc-packages-docs/index.mjs && typedoc && node ./tools/typedoc-yandex-metrica/index.mjs",
+    "repl": "dotenv -e .env -- npm run build && node -e \"import('./scripts/repl.mjs')\" --interactive"
+  },
+  "main": "build/index.cjs",
+  "module": "build/index.mjs",
+  "source": "src/index.ts",
+  "types": "./types.d.ts",
+  "exports": {
+    "require": "./build/index.cjs",
+    "types": "./types.d.ts",
+    "import": "./build/index.mjs",
+    "default": "./build/index.cjs"
+  },
+  "devDependencies": {
+    "@rollup/plugin-typescript": "11.1.6",
+    "@types/node": "22.9.0",
+    "glob": "11.0.1",
+    "plantuml": "0.0.2",
+    "rimraf": "6.0.1",
+    "rollup": "3.29.5",
+    "rollup-plugin-dts": "6.1.1",
+    "rollup-plugin-peer-deps-external": "2.2.4",
+    "ts-morph": "27.0.2",
+    "tslib": "2.7.0",
+    "typedoc": "0.27.9",
+    "worker-testbed": "2.0.0"
+  },
+  "peerDependencies": {
+    "typescript": "^5.0.0"
+  },
+  "dependencies": {
+    "di-kit": "^1.1.1",
+    "di-scoped": "^1.0.21",
+    "di-singleton": "^1.0.5",
+    "functools-kit": "^2.3.0",
+    "get-moment-stamp": "^2.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}