backtest-kit 11.4.0 → 11.5.2

package/build/index.cjs

@@ -23885,13 +23885,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;
@@ -24049,7 +24070,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)`}`,
@@ -24067,11 +24088,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");
     }
@@ -24820,15 +24842,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;
@@ -24927,7 +24971,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)`}`,
@@ -24945,11 +24989,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");
     }
@@ -26861,6 +26906,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;
@@ -26869,6 +26920,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;
@@ -27155,9 +27218,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) {
@@ -27189,13 +27263,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;
@@ -27208,20 +27296,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
@@ -27318,8 +27429,17 @@ class HeatmapStorage {
         return [
             `# 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"}`,
+            `**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 Per Trade:** ${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,
             "",
@@ -27329,10 +27449,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");
     }