backtest-kit 11.6.0 → 11.7.0

package/README.md

@@ -80,7 +80,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**: 770+ unit/integration tests for validation, recovery, and events.
+- 🧪 **Tested**: 775+ 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
@@ -1984,7 +1984,7 @@ Python-based (WASI) strategy that uses EMA(9) and EMA(21) crossover signals exec
 
 ## ✅ Tested & Reliable
 
-770+ tests cover validation, recovery, reports, and events.
+775+ tests cover validation, recovery, reports, and events.
 
 ## 🤝 Contribute
 

package/build/index.cjs

@@ -23978,13 +23978,19 @@ let ReportStorage$a = class ReportStorage {
         // mark-to-market low); equity then moves to the realized close.
         // If equity (at trough or close) goes ≤ 0 (e.g. leveraged loss < -100%) — account
         // blown, fix DD at 100% and stop walking the curve.
+        // Walk the equity curve in chronological close order. Storage is
+        // newest-first (unshift on addSignal); reverse-storage iteration normally
+        // gives chronological order, but explicitly sorting by closeTimestamp
+        // removes the dependency on insertion-order matching close-order (which
+        // can break under crash recovery, signal backfill, or disk replays).
+        const orderedSignals = [...validSignals].sort((a, b) => a.closeTimestamp - b.closeTimestamp);
         let equity = 1;
         let peak = 1;
         let equityMaxDrawdown = 0;
         let blown = false;
-        for (let i = validSignals.length - 1; i >= 0; i--) {
+        for (const s of orderedSignals) {
             // Intra-trade trough — mark-to-market low while the position was open.
-            const fallPct = validSignals[i].signal.maxDrawdown?.pnlPercentage;
+            const fallPct = s.signal.maxDrawdown?.pnlPercentage;
             if (typeof fallPct === "number" && fallPct < 0) {
                 const trough = equity * (1 + fallPct / 100);
                 if (trough <= 0) {
@@ -23997,7 +24003,7 @@ let ReportStorage$a = class ReportStorage {
                     equityMaxDrawdown = troughDd;
             }
             // Realized close — book the final per-trade result.
-            equity *= 1 + validSignals[i].pnl.pnlPercentage / 100;
+            equity *= 1 + s.pnl.pnlPercentage / 100;
             if (equity <= 0) {
                 equityMaxDrawdown = 100;
                 blown = true;
@@ -25142,14 +25148,20 @@ let ReportStorage$9 = class ReportStorage {
         // snapshot, ≤ 0) is applied as a trough BEFORE booking the realized close. Without it
         // the curve only steps at close, so a trade that dipped to -18% and recovered to +2%
         // would register zero drawdown — understating DD and inflating Calmar/Recovery.
-        const chronological = [];
-        for (let i = validClosed.length - 1; i >= 0; i--) {
-            const fall = validClosed[i].fallPnl;
-            chronological.push({
-                r: validClosed[i].pnl,
-                fall: typeof fall === "number" ? fall : null,
-            });
-        }
+        // Walk the equity curve in chronological close order. Reverse-storage
+        // iteration (newest-first storage → reverse) normally yields chronological
+        // order for live ingest, but explicitly sorting by event.timestamp removes
+        // the dependency on insertion-order matching close-order. This matters
+        // under crash recovery (events reloaded from disk in arbitrary order) and
+        // when ingest latency reorders closed events relative to wall-clock time.
+        const chronological = validClosed
+            .map((e) => ({
+            r: e.pnl,
+            fall: typeof e.fallPnl === "number" ? e.fallPnl : null,
+            ts: e.timestamp,
+        }))
+            .sort((a, b) => a.ts - b.ts)
+            .map(({ r, fall }) => ({ r, fall }));
         let equity = 1;
         let peak = 1;
         let equityMaxDrawdown = 0;
@@ -27223,11 +27235,18 @@ class HeatmapStorage {
         let equityFinal = 1;
         let blown = false;
         if (signals.length > 0) {
+            // Walk the per-symbol equity curve in chronological close order.
+            // Storage is newest-first (unshift on addSignal), but if signals were
+            // ingested out-of-order (e.g. Live + crash recovery loading from disk in
+            // arbitrary order, or a backfill replay), reverse-storage iteration
+            // would misplace peak/trough and silently distort maxDrawdown. Sorting
+            // by closeTimestamp explicitly removes that dependency.
+            const ordered = [...signals].sort((a, b) => a.closeTimestamp - b.closeTimestamp);
             let equity = 1;
             let peak = 1;
             let maxDD = 0;
-            for (let i = signals.length - 1; i >= 0; i--) {
-                const fallPct = signals[i].signal.maxDrawdown?.pnlPercentage;
+            for (const s of ordered) {
+                const fallPct = s.signal.maxDrawdown?.pnlPercentage;
                 if (typeof fallPct === "number" && fallPct < 0) {
                     const trough = equity * (1 + fallPct / 100);
                     if (trough <= 0) {
@@ -27239,7 +27258,7 @@ class HeatmapStorage {
                     if (troughDd > maxDD)
                         maxDD = troughDd;
                 }
-                equity *= 1 + signals[i].pnl.pnlPercentage / 100;
+                equity *= 1 + s.pnl.pnlPercentage / 100;
                 if (equity <= 0) {
                     maxDD = 100;
                     blown = true;
@@ -27676,23 +27695,28 @@ class HeatmapStorage {
         let portfolioCertaintyRatio = null;
         let portfolioExpectedYearlyReturns = null;
         let portfolioTradesPerYear = null;
-        const allReturns = [];
-        // Parallel array of intra-trade troughs (≤ 0), aligned 1:1 with allReturns,
-        // used for mark-to-market DD in the pooled equity curve below.
-        const allFalls = [];
+        const pooledTrades = [];
         let poolFirstPendingAt = Infinity;
         let poolLastCloseAt = -Infinity;
         for (const signals of this.symbolData.values()) {
             for (const s of signals) {
-                allReturns.push(s.pnl.pnlPercentage);
                 const fall = s.signal.maxDrawdown?.pnlPercentage;
-                allFalls.push(typeof fall === "number" ? fall : null);
+                pooledTrades.push({
+                    r: s.pnl.pnlPercentage,
+                    fall: typeof fall === "number" ? fall : null,
+                    closeAt: s.closeTimestamp,
+                });
                 if (s.signal.pendingAt < poolFirstPendingAt)
                     poolFirstPendingAt = s.signal.pendingAt;
                 if (s.closeTimestamp > poolLastCloseAt)
                     poolLastCloseAt = s.closeTimestamp;
             }
         }
+        pooledTrades.sort((a, b) => a.closeAt - b.closeAt);
+        const allReturns = pooledTrades.map((t) => t.r);
+        // Parallel array of intra-trade troughs (≤ 0), aligned 1:1 with allReturns,
+        // used for mark-to-market DD in the pooled equity curve below.
+        const allFalls = pooledTrades.map((t) => t.fall);
         if (allReturns.length >= MIN_SIGNALS_FOR_RATIOS) {
             const portfolioAvg = allReturns.reduce((acc, r) => acc + r, 0) / allReturns.length;
             const portfolioVariance = allReturns.reduce((acc, r) => acc + Math.pow(r - portfolioAvg, 2), 0) /
@@ -28066,7 +28090,7 @@ class HeatmapStorage {
             `*Peak Profit PNL / Max Drawdown PNL: extremes — the best best-case and worst worst-case observed across all trades. Tail behaviour the averages hide.*`,
             `*Avg Duration / Avg Win Duration / Avg Loss Duration: mean hold time in minutes (closeTimestamp - pendingAt). Winner-shorter-than-loser is a red flag ("cut winners short, let losers run").*`,
             `*Avg Consecutive Win/Loss PNL: average sum of pnlPercentage across consecutive streaks. Pairs with max streak length to show the typical (not worst-case) streak magnitude. Portfolio uses trade-count-weighted mean of per-symbol streak averages — concatenating streaks across symbols would be meaningless (different markets, different timeframes).*`,
-            `*Max Drawdown: mark-to-market — both the per-symbol and pooled equity curves apply each trade's worst intra-trade excursion (the lowest unrealized point while the position was open) before booking its realized close, so deep round-trip dips count. It is NOT realized-only (close-to-close); a realized-only curve would understate drawdown and inflate Calmar/Recovery. NOTE: the pooled curve orders trades by storage sequence, not wall-clock time, so simultaneous cross-symbol drawdowns are not modelled.*`,
+            `*Max Drawdown: mark-to-market — both the per-symbol and pooled equity curves apply each trade's worst intra-trade excursion (the lowest unrealized point while the position was open) before booking its realized close, so deep round-trip dips count. It is NOT realized-only (close-to-close); a realized-only curve would understate drawdown and inflate Calmar/Recovery. The pooled curve walks trades chronologically by closeTimestamp; simultaneous cross-symbol drawdowns within the same minute are still serialised (one trade applied at a time), so genuine same-instant tail correlation is not modelled.*`,
             `*All metrics require 100+ signals per symbol to be statistically reliable. Annualized metrics assume the observed trading frequency persists year-round.*`,
             `*IMPORTANT: Per-symbol equity curve, Expected Yearly Returns, Calmar, Recovery and Max Drawdown all assume **100% capital allocation per position** (no portfolio fraction). These metrics ignore the position-sizing subsystem (PositionSize / Kelly / ATR): pnlPercentage is a return on the position's own invested capital, never scaled by account balance. With DCA (commitAverageBuy) the cost basis is the sum of all entries and the entry price is dollar-cost-weighted, so per-trade % is measured against the averaged position, not a fixed stake. If your strategy risks X% of capital per trade, the realized return / drawdown will be roughly X/100 of the reported figures — these metrics represent a theoretical upper bound under full allocation.*`,
             `*Negative values for Sharpe / Annualized Sharpe / Sortino / Calmar / Recovery / Expectancy / Expected Yearly Returns indicate a losing symbol (avgPnl < 0 or totalPnl < 0). "Higher is better" still applies — closer to zero is less bad, positive is profitable.*`,

package/build/index.mjs

@@ -23958,13 +23958,19 @@ let ReportStorage$a = class ReportStorage {
         // mark-to-market low); equity then moves to the realized close.
         // If equity (at trough or close) goes ≤ 0 (e.g. leveraged loss < -100%) — account
         // blown, fix DD at 100% and stop walking the curve.
+        // Walk the equity curve in chronological close order. Storage is
+        // newest-first (unshift on addSignal); reverse-storage iteration normally
+        // gives chronological order, but explicitly sorting by closeTimestamp
+        // removes the dependency on insertion-order matching close-order (which
+        // can break under crash recovery, signal backfill, or disk replays).
+        const orderedSignals = [...validSignals].sort((a, b) => a.closeTimestamp - b.closeTimestamp);
         let equity = 1;
         let peak = 1;
         let equityMaxDrawdown = 0;
         let blown = false;
-        for (let i = validSignals.length - 1; i >= 0; i--) {
+        for (const s of orderedSignals) {
             // Intra-trade trough — mark-to-market low while the position was open.
-            const fallPct = validSignals[i].signal.maxDrawdown?.pnlPercentage;
+            const fallPct = s.signal.maxDrawdown?.pnlPercentage;
             if (typeof fallPct === "number" && fallPct < 0) {
                 const trough = equity * (1 + fallPct / 100);
                 if (trough <= 0) {
@@ -23977,7 +23983,7 @@ let ReportStorage$a = class ReportStorage {
                     equityMaxDrawdown = troughDd;
             }
             // Realized close — book the final per-trade result.
-            equity *= 1 + validSignals[i].pnl.pnlPercentage / 100;
+            equity *= 1 + s.pnl.pnlPercentage / 100;
             if (equity <= 0) {
                 equityMaxDrawdown = 100;
                 blown = true;
@@ -25122,14 +25128,20 @@ let ReportStorage$9 = class ReportStorage {
         // snapshot, ≤ 0) is applied as a trough BEFORE booking the realized close. Without it
         // the curve only steps at close, so a trade that dipped to -18% and recovered to +2%
         // would register zero drawdown — understating DD and inflating Calmar/Recovery.
-        const chronological = [];
-        for (let i = validClosed.length - 1; i >= 0; i--) {
-            const fall = validClosed[i].fallPnl;
-            chronological.push({
-                r: validClosed[i].pnl,
-                fall: typeof fall === "number" ? fall : null,
-            });
-        }
+        // Walk the equity curve in chronological close order. Reverse-storage
+        // iteration (newest-first storage → reverse) normally yields chronological
+        // order for live ingest, but explicitly sorting by event.timestamp removes
+        // the dependency on insertion-order matching close-order. This matters
+        // under crash recovery (events reloaded from disk in arbitrary order) and
+        // when ingest latency reorders closed events relative to wall-clock time.
+        const chronological = validClosed
+            .map((e) => ({
+            r: e.pnl,
+            fall: typeof e.fallPnl === "number" ? e.fallPnl : null,
+            ts: e.timestamp,
+        }))
+            .sort((a, b) => a.ts - b.ts)
+            .map(({ r, fall }) => ({ r, fall }));
         let equity = 1;
         let peak = 1;
         let equityMaxDrawdown = 0;
@@ -27203,11 +27215,18 @@ class HeatmapStorage {
         let equityFinal = 1;
         let blown = false;
         if (signals.length > 0) {
+            // Walk the per-symbol equity curve in chronological close order.
+            // Storage is newest-first (unshift on addSignal), but if signals were
+            // ingested out-of-order (e.g. Live + crash recovery loading from disk in
+            // arbitrary order, or a backfill replay), reverse-storage iteration
+            // would misplace peak/trough and silently distort maxDrawdown. Sorting
+            // by closeTimestamp explicitly removes that dependency.
+            const ordered = [...signals].sort((a, b) => a.closeTimestamp - b.closeTimestamp);
             let equity = 1;
             let peak = 1;
             let maxDD = 0;
-            for (let i = signals.length - 1; i >= 0; i--) {
-                const fallPct = signals[i].signal.maxDrawdown?.pnlPercentage;
+            for (const s of ordered) {
+                const fallPct = s.signal.maxDrawdown?.pnlPercentage;
                 if (typeof fallPct === "number" && fallPct < 0) {
                     const trough = equity * (1 + fallPct / 100);
                     if (trough <= 0) {
@@ -27219,7 +27238,7 @@ class HeatmapStorage {
                     if (troughDd > maxDD)
                         maxDD = troughDd;
                 }
-                equity *= 1 + signals[i].pnl.pnlPercentage / 100;
+                equity *= 1 + s.pnl.pnlPercentage / 100;
                 if (equity <= 0) {
                     maxDD = 100;
                     blown = true;
@@ -27656,23 +27675,28 @@ class HeatmapStorage {
         let portfolioCertaintyRatio = null;
         let portfolioExpectedYearlyReturns = null;
         let portfolioTradesPerYear = null;
-        const allReturns = [];
-        // Parallel array of intra-trade troughs (≤ 0), aligned 1:1 with allReturns,
-        // used for mark-to-market DD in the pooled equity curve below.
-        const allFalls = [];
+        const pooledTrades = [];
         let poolFirstPendingAt = Infinity;
         let poolLastCloseAt = -Infinity;
         for (const signals of this.symbolData.values()) {
             for (const s of signals) {
-                allReturns.push(s.pnl.pnlPercentage);
                 const fall = s.signal.maxDrawdown?.pnlPercentage;
-                allFalls.push(typeof fall === "number" ? fall : null);
+                pooledTrades.push({
+                    r: s.pnl.pnlPercentage,
+                    fall: typeof fall === "number" ? fall : null,
+                    closeAt: s.closeTimestamp,
+                });
                 if (s.signal.pendingAt < poolFirstPendingAt)
                     poolFirstPendingAt = s.signal.pendingAt;
                 if (s.closeTimestamp > poolLastCloseAt)
                     poolLastCloseAt = s.closeTimestamp;
             }
         }
+        pooledTrades.sort((a, b) => a.closeAt - b.closeAt);
+        const allReturns = pooledTrades.map((t) => t.r);
+        // Parallel array of intra-trade troughs (≤ 0), aligned 1:1 with allReturns,
+        // used for mark-to-market DD in the pooled equity curve below.
+        const allFalls = pooledTrades.map((t) => t.fall);
         if (allReturns.length >= MIN_SIGNALS_FOR_RATIOS) {
             const portfolioAvg = allReturns.reduce((acc, r) => acc + r, 0) / allReturns.length;
             const portfolioVariance = allReturns.reduce((acc, r) => acc + Math.pow(r - portfolioAvg, 2), 0) /
@@ -28046,7 +28070,7 @@ class HeatmapStorage {
             `*Peak Profit PNL / Max Drawdown PNL: extremes — the best best-case and worst worst-case observed across all trades. Tail behaviour the averages hide.*`,
             `*Avg Duration / Avg Win Duration / Avg Loss Duration: mean hold time in minutes (closeTimestamp - pendingAt). Winner-shorter-than-loser is a red flag ("cut winners short, let losers run").*`,
             `*Avg Consecutive Win/Loss PNL: average sum of pnlPercentage across consecutive streaks. Pairs with max streak length to show the typical (not worst-case) streak magnitude. Portfolio uses trade-count-weighted mean of per-symbol streak averages — concatenating streaks across symbols would be meaningless (different markets, different timeframes).*`,
-            `*Max Drawdown: mark-to-market — both the per-symbol and pooled equity curves apply each trade's worst intra-trade excursion (the lowest unrealized point while the position was open) before booking its realized close, so deep round-trip dips count. It is NOT realized-only (close-to-close); a realized-only curve would understate drawdown and inflate Calmar/Recovery. NOTE: the pooled curve orders trades by storage sequence, not wall-clock time, so simultaneous cross-symbol drawdowns are not modelled.*`,
+            `*Max Drawdown: mark-to-market — both the per-symbol and pooled equity curves apply each trade's worst intra-trade excursion (the lowest unrealized point while the position was open) before booking its realized close, so deep round-trip dips count. It is NOT realized-only (close-to-close); a realized-only curve would understate drawdown and inflate Calmar/Recovery. The pooled curve walks trades chronologically by closeTimestamp; simultaneous cross-symbol drawdowns within the same minute are still serialised (one trade applied at a time), so genuine same-instant tail correlation is not modelled.*`,
             `*All metrics require 100+ signals per symbol to be statistically reliable. Annualized metrics assume the observed trading frequency persists year-round.*`,
             `*IMPORTANT: Per-symbol equity curve, Expected Yearly Returns, Calmar, Recovery and Max Drawdown all assume **100% capital allocation per position** (no portfolio fraction). These metrics ignore the position-sizing subsystem (PositionSize / Kelly / ATR): pnlPercentage is a return on the position's own invested capital, never scaled by account balance. With DCA (commitAverageBuy) the cost basis is the sum of all entries and the entry price is dollar-cost-weighted, so per-trade % is measured against the averaged position, not a fixed stake. If your strategy risks X% of capital per trade, the realized return / drawdown will be roughly X/100 of the reported figures — these metrics represent a theoretical upper bound under full allocation.*`,
             `*Negative values for Sharpe / Annualized Sharpe / Sortino / Calmar / Recovery / Expectancy / Expected Yearly Returns indicate a losing symbol (avgPnl < 0 or totalPnl < 0). "Higher is better" still applies — closer to zero is less bad, positive is profitable.*`,

package/package.json

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