backtest-kit 10.1.0 → 11.0.0

package/build/index.mjs

@@ -1,7 +1,7 @@
 import { createActivator } from 'di-kit';
 import { scoped } from 'di-scoped';
 import { singleton } from 'di-singleton';
-import { Subject, makeExtendable, singleshot, getErrorMessage, memoize, not, errorData, trycatch, retry, queued, sleep, randomString, str, isObject, ToolRegistry, typo, and, Source, resolveDocuments, timeout, TIMEOUT_SYMBOL as TIMEOUT_SYMBOL$1, compose, BehaviorSubject, waitForNext, singlerun } from 'functools-kit';
+import { Subject, BehaviorSubject, makeExtendable, singleshot, getErrorMessage, memoize, not, errorData, trycatch, retry, queued, sleep, randomString, str, isObject, ToolRegistry, typo, and, Source, resolveDocuments, timeout, TIMEOUT_SYMBOL as TIMEOUT_SYMBOL$2, compose, waitForNext, singlerun } from 'functools-kit';
 import * as fs from 'fs/promises';
 import fs__default from 'fs/promises';
 import path, { join, dirname } from 'path';
@@ -798,6 +798,13 @@ const beforeStartSubject = new Subject();
  * Emits when the engine has completed processing a signal.
  */
 const afterEndSubject = new Subject();
+/**
+ * Emitter for `@backtest-kit/cli`, which notifies the application
+ * that all modules have been initialized.
+ *
+ * Send entry absolute path to the consumer
+ */
+const entrySubject = new BehaviorSubject();
 
 var emitters = /*#__PURE__*/Object.freeze({
     __proto__: null,
@@ -809,6 +816,7 @@ var emitters = /*#__PURE__*/Object.freeze({
     doneBacktestSubject: doneBacktestSubject,
     doneLiveSubject: doneLiveSubject,
     doneWalkerSubject: doneWalkerSubject,
+    entrySubject: entrySubject,
     errorEmitter: errorEmitter,
     exitEmitter: exitEmitter,
     highestProfitSubject: highestProfitSubject,
@@ -6564,7 +6572,7 @@ const INTERVAL_MINUTES$8 = {
  * Used to indicate that the actual pendingAt will be set upon activation.
  */
 const SCHEDULED_SIGNAL_PENDING_MOCK = 0;
-const TIMEOUT_SYMBOL = Symbol('timeout');
+const TIMEOUT_SYMBOL$1 = Symbol('timeout');
 /**
  * Calls onSignalSync callback for signal-open event.
  *
@@ -6986,7 +6994,7 @@ const GET_SIGNAL_FN = trycatch(async (self) => {
     const timeoutMs = GLOBAL_CONFIG.CC_MAX_SIGNAL_GENERATION_SECONDS * 1000;
     const signal = await Promise.race([
         self.params.getSignal(self.params.execution.context.symbol, self.params.execution.context.when, currentPrice),
-        sleep(timeoutMs).then(() => TIMEOUT_SYMBOL),
+        sleep(timeoutMs).then(() => TIMEOUT_SYMBOL$1),
     ]);
     if (typeof signal === "symbol") {
         throw new Error(`Timeout for ${self.params.method.context.strategyName} symbol=${self.params.execution.context.symbol}`);
@@ -23252,7 +23260,7 @@ class MarkdownFileBase {
             timestamp: getContextTimestamp(),
         }) + "\n";
         const status = await this[WRITE_SAFE_SYMBOL$1](line);
-        if (status === TIMEOUT_SYMBOL$1) {
+        if (status === TIMEOUT_SYMBOL$2) {
             throw new Error(`Timeout writing to markdown ${this.markdownName}`);
         }
     }
@@ -23545,7 +23553,7 @@ class ReportBase {
             timestamp: getContextTimestamp(),
         }) + "\n";
         const status = await this[WRITE_SAFE_SYMBOL$1](line);
-        if (status === TIMEOUT_SYMBOL$1) {
+        if (status === TIMEOUT_SYMBOL$2) {
             throw new Error(`Timeout writing to report ${this.reportName}`);
         }
     }
@@ -23706,7 +23714,7 @@ const CREATE_FILE_NAME_FN$c = (symbol, strategyName, exchangeName, frameName, ti
  * @param value - Value to check
  * @returns true if value is unsafe, false otherwise
  */
-function isUnsafe$3(value) {
+function isUnsafe$4(value) {
     if (typeof value !== "number") {
         return true;
     }
@@ -23718,6 +23726,25 @@ function isUnsafe$3(value) {
     }
     return false;
 }
+/** Minimum closed signals required to annualize Sharpe / yearly returns / Calmar. */
+const MIN_SIGNALS_FOR_ANNUALIZATION$2 = 10;
+/** Minimum signals required for ANY ratio metric (Sharpe / Sortino / stdDev). Below this,
+ *  sample size is too small to estimate variance meaningfully. */
+const MIN_SIGNALS_FOR_RATIOS$2 = 10;
+/** Minimum calendar span (days) for trade-frequency extrapolation. */
+const MIN_CALENDAR_SPAN_DAYS$2 = 14;
+/** Hard cap on tradesPerYear — prevents absurd extrapolation from short windows / clustered trades. */
+const MAX_TRADES_PER_YEAR$2 = 365;
+/** Hard cap on |expectedYearlyReturns| percent. Compound interest on high avgPnl × frequency
+ *  blows up to mathematically correct but business-unrealistic values. ±100% = 2x equity —
+ *  anything above this we suspect is a noisy estimate, not a genuine edge. Above the cap → null. */
+const MAX_EXPECTED_YEARLY_RETURNS$2 = 100;
+/** Hard cap on |calmarRatio|. Prevents explosion when equityMaxDrawdown is near zero. */
+const MAX_CALMAR_RATIO$2 = 1000;
+/** Minimum stdDev required for Sharpe/Sortino computation. Identical-returns series produce
+ *  float-artifact stdDev (~1e-17) that's mathematically > 0 but spuriously inflates
+ *  sharpe to astronomical values. Treat any stdDev below this threshold as zero. */
+const STDDEV_EPSILON$2 = 1e-9;
 /**
  * Storage class for accumulating closed signals per strategy.
  * Maintains a list of all closed signals and provides methods to generate reports.
@@ -23771,65 +23798,190 @@ let ReportStorage$a = class ReportStorage {
                 recoveryFactor: null,
             };
         }
-        const totalSignals = this._signalList.length;
-        const winCount = this._signalList.filter((s) => s.pnl.pnlPercentage > 0).length;
-        const lossCount = this._signalList.filter((s) => s.pnl.pnlPercentage < 0).length;
-        // Calculate basic statistics
-        const avgPnl = this._signalList.reduce((sum, s) => sum + s.pnl.pnlPercentage, 0) / totalSignals;
-        const totalPnl = this._signalList.reduce((sum, s) => sum + s.pnl.pnlPercentage, 0);
-        const winRate = (winCount / totalSignals) * 100;
-        // Calculate Sharpe Ratio (risk-free rate = 0)
-        const returns = this._signalList.map((s) => s.pnl.pnlPercentage);
-        const variance = returns.reduce((sum, r) => sum + Math.pow(r - avgPnl, 2), 0) / totalSignals;
-        const stdDev = Math.sqrt(variance);
-        const sharpeRatio = stdDev > 0 ? avgPnl / stdDev : 0;
-        const annualizedSharpeRatio = sharpeRatio * Math.sqrt(365);
-        // Calculate Certainty Ratio
-        const wins = this._signalList.filter((s) => s.pnl.pnlPercentage > 0);
-        const losses = this._signalList.filter((s) => s.pnl.pnlPercentage < 0);
+        // Valid signal set — those with usable pendingAt AND closeTimestamp. Single source
+        // of truth for EVERY metric in this method (counts, sums, span, equity curve,
+        // ratios, annualization). If we used different subsets for different metrics, the
+        // numerator of one ratio could be drawn from a different population than the
+        // denominator of another and the report would silently lie. On clean data
+        // validSignals === this._signalList; the filter only matters for corrupted runtime
+        // data.
+        const validSignals = this._signalList.filter((s) => typeof s.signal.pendingAt === "number" && s.signal.pendingAt > 0 &&
+            typeof s.closeTimestamp === "number" && s.closeTimestamp > 0);
+        const totalSignals = validSignals.length;
+        const winCount = validSignals.filter((s) => s.pnl.pnlPercentage > 0).length;
+        const lossCount = validSignals.filter((s) => s.pnl.pnlPercentage < 0).length;
+        // Basic statistics — guard against an empty validSignals (e.g. every signal had
+        // corrupted timestamps) so we don't divide by zero.
+        const avgPnl = totalSignals > 0
+            ? validSignals.reduce((sum, s) => sum + s.pnl.pnlPercentage, 0) / totalSignals
+            : 0;
+        const totalPnl = validSignals.reduce((sum, s) => sum + s.pnl.pnlPercentage, 0);
+        // Win rate excludes break-even trades from both numerator and denominator.
+        const decisiveTrades = winCount + lossCount;
+        const winRate = decisiveTrades > 0 ? (winCount / decisiveTrades) * 100 : 0;
+        // Calendar span over the same validSignals set used for ratios.
+        let firstPendingAt = Infinity;
+        let lastCloseAt = -Infinity;
+        for (const s of validSignals) {
+            if (s.signal.pendingAt < firstPendingAt)
+                firstPendingAt = s.signal.pendingAt;
+            if (s.closeTimestamp > lastCloseAt)
+                lastCloseAt = s.closeTimestamp;
+        }
+        const calendarSpanDays = isFinite(firstPendingAt) && isFinite(lastCloseAt)
+            ? (lastCloseAt - firstPendingAt) / (1000 * 60 * 60 * 24)
+            : 0;
+        // tradesPerYear uses the RAW observed frequency — no clipping. Clipping would
+        // silently understate Sharpe / Calmar / expectedYearlyReturns. Instead, if the
+        // raw frequency exceeds MAX_TRADES_PER_YEAR we treat the sample as too clustered
+        // for reliable annualization and surface every annualized metric as null.
+        const rawTradesPerYear = totalSignals >= MIN_SIGNALS_FOR_ANNUALIZATION$2 &&
+            calendarSpanDays >= MIN_CALENDAR_SPAN_DAYS$2
+            ? (totalSignals / calendarSpanDays) * 365
+            : 0;
+        const canAnnualize = rawTradesPerYear > 0 && rawTradesPerYear <= MAX_TRADES_PER_YEAR$2;
+        const tradesPerYear = canAnnualize ? rawTradesPerYear : 0;
+        // Per-trade Sharpe Ratio (risk-free rate = 0). Sample stddev (N-1) for unbiased estimate.
+        // Per-trade ratios are gated by MIN_SIGNALS_FOR_RATIOS — below that, variance estimates
+        // are too noisy to publish (high chance of spurious ±Sharpe).
+        const returns = validSignals.map((s) => s.pnl.pnlPercentage);
+        const canComputeRatios = totalSignals >= MIN_SIGNALS_FOR_RATIOS$2;
+        const stdDev = canComputeRatios
+            ? Math.sqrt(returns.reduce((sum, r) => sum + Math.pow(r - avgPnl, 2), 0) / (totalSignals - 1))
+            : 0;
+        // Use STDDEV_EPSILON gate (not stdDev > 0) — identical-returns series produce
+        // float-artifact stdDev (~1e-17) that's mathematically > 0 but spuriously
+        // inflates sharpe to astronomical magnitudes (avgPnl / epsilon).
+        const sharpeRatio = canComputeRatios && stdDev > STDDEV_EPSILON$2
+            ? avgPnl / stdDev
+            : null;
+        // Annualize only when gate passes; otherwise null.
+        const annualizedSharpeRatio = canAnnualize && sharpeRatio !== null
+            ? sharpeRatio * Math.sqrt(tradesPerYear)
+            : null;
+        // Equity-curve max drawdown via compounded equity (multiplicative, not additive).
+        // Returns are per-trade on cost basis — compounding assumes equal capital allocation
+        // 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.
+        let equity = 1;
+        let peak = 1;
+        let equityMaxDrawdown = 0;
+        let blown = false;
+        for (let i = validSignals.length - 1; i >= 0; i--) {
+            equity *= 1 + validSignals[i].pnl.pnlPercentage / 100;
+            if (equity <= 0) {
+                equityMaxDrawdown = 100;
+                blown = true;
+                break;
+            }
+            if (equity > peak)
+                peak = equity;
+            const dd = (peak - equity) / peak * 100;
+            if (dd > equityMaxDrawdown)
+                equityMaxDrawdown = dd;
+        }
+        const equityFinal = blown ? 0 : equity;
+        // Compounded yearly return via geometric mean of equity curve.
+        // equityFinal^(tradesPerYear / N) - 1 — accounts for volatility drag that
+        // arithmetic-mean compounding ((1+avgPnl)^N) misses. If account is blown, full loss.
+        // If the raw value would exceed MAX_EXPECTED_YEARLY_RETURNS, return null rather than
+        // showing the cap as a real figure — capped numbers mislead users into trusting them.
+        const expectedYearlyReturns = canAnnualize
+            ? blown
+                ? -100
+                : (() => {
+                    // Geometric annualization uses validSignals.length (same set that defined
+                    // tradesPerYear); using totalSignals here would mismatch numerator/denominator.
+                    const raw = (Math.pow(equityFinal, tradesPerYear / validSignals.length) - 1) * 100;
+                    return Math.abs(raw) > MAX_EXPECTED_YEARLY_RETURNS$2 ? null : raw;
+                })()
+            : null;
+        // Certainty Ratio — over validSignals so wins/losses come from the same set as
+        // winCount/lossCount/avgPnl above.
+        const wins = validSignals.filter((s) => s.pnl.pnlPercentage > 0);
+        const losses = validSignals.filter((s) => s.pnl.pnlPercentage < 0);
         const avgWin = wins.length > 0
             ? wins.reduce((sum, s) => sum + s.pnl.pnlPercentage, 0) / wins.length
             : 0;
         const avgLoss = losses.length > 0
             ? losses.reduce((sum, s) => sum + s.pnl.pnlPercentage, 0) / losses.length
             : 0;
-        const certaintyRatio = avgLoss < 0 ? avgWin / Math.abs(avgLoss) : 0;
-        // Calculate Expected Yearly Returns
-        const avgDurationMs = this._signalList.reduce((sum, s) => sum + (s.closeTimestamp - s.signal.pendingAt), 0) / totalSignals;
-        const avgDurationDays = avgDurationMs / (1000 * 60 * 60 * 24);
-        const tradesPerYear = avgDurationDays > 0 ? 365 / avgDurationDays : 0;
-        const expectedYearlyReturns = avgPnl * tradesPerYear;
-        // Calculate average peak and fall PNL across all signals
-        const avgPeakPnl = this._signalList.reduce((sum, s) => sum + (s.signal.peakProfit?.pnlPercentage ?? 0), 0) / totalSignals;
-        const avgFallPnl = this._signalList.reduce((sum, s) => sum + (s.signal.maxDrawdown?.pnlPercentage ?? 0), 0) / totalSignals;
-        // Downside per signal: maxDrawdown.pnlPercentage captures the worst intra-trade dip
-        const fallReturns = this._signalList.map((s) => s.signal.maxDrawdown?.pnlPercentage ?? 0);
-        // Calculate Sortino Ratio: avgPnl / stdDev(maxDrawdown per signal)
-        const fallVariance = fallReturns.reduce((sum, r) => sum + Math.pow(r, 2), 0) / totalSignals;
-        const fallDeviation = Math.sqrt(fallVariance);
-        const sortinoRatio = fallDeviation > 0 ? avgPnl / fallDeviation : 0;
-        // Max absolute drawdown across all signals — used as denominator for Calmar and Recovery
-        const maxAbsFall = fallReturns.reduce((max, r) => Math.max(max, Math.abs(r)), 0);
-        const calmarRatio = maxAbsFall > 0 ? expectedYearlyReturns / maxAbsFall : 0;
-        const recoveryFactor = maxAbsFall > 0 ? totalPnl / maxAbsFall : 0;
+        // Null below MIN_SIGNALS_FOR_RATIOS — on a handful of trades the win/loss
+        // means are too noisy to publish a ratio (same sample-size gate as Sharpe/
+        // Sortino, so the report doesn't surface certainty while withholding the rest).
+        // Also null when no losing trades OR when |avgLoss| is below STDDEV_EPSILON
+        // (float-artifact losses (-1e-15) would otherwise produce a spurious
+        // astronomical certaintyRatio ≈1e14).
+        const certaintyRatio = canComputeRatios && Math.abs(avgLoss) > STDDEV_EPSILON$2 && avgLoss < 0
+            ? avgWin / Math.abs(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
+            .map((s) => s.signal.peakProfit?.pnlPercentage)
+            .filter((v) => typeof v === "number");
+        const fallValues = validSignals
+            .map((s) => s.signal.maxDrawdown?.pnlPercentage)
+            .filter((v) => typeof v === "number");
+        const avgPeakPnl = peakValues.length > 0
+            ? peakValues.reduce((sum, v) => sum + v, 0) / peakValues.length
+            : null;
+        const avgFallPnl = fallValues.length > 0
+            ? fallValues.reduce((sum, v) => sum + v, 0) / fallValues.length
+            : null;
+        // Sortino (canonical, Sortino 1991): (avgPnl - MAR) / downside deviation, where
+        // downsideDev = √( Σ min(0, r - MAR)² / N_total ). We use MAR = 0 (risk-free target),
+        // so the numerator reduces to avgPnl and the squared term to r² for r < 0.
+        // Dividing by N_total (not N_negative) properly penalises strategies with frequent
+        // losses; the "modified" form (N_negative) hides frequency risk in catastrophic-tail
+        // strategies.
+        const negativeReturns = returns.filter((r) => r < 0);
+        const sortinoRatio = (() => {
+            if (!canComputeRatios)
+                return null;
+            if (negativeReturns.length === 0)
+                return null;
+            const downsideVariance = negativeReturns.reduce((sum, r) => sum + r * r, 0) / returns.length;
+            const downsideDeviation = Math.sqrt(downsideVariance);
+            // Same epsilon guard as Sharpe — protects against float-artifact downsideDev.
+            return downsideDeviation > STDDEV_EPSILON$2 ? avgPnl / downsideDeviation : null;
+        })();
+        // Calmar — cap |value| at MAX_CALMAR_RATIO to prevent explosion when DD is near zero.
+        const calmarRatio = equityMaxDrawdown > 0 && expectedYearlyReturns !== null
+            ? Math.max(-MAX_CALMAR_RATIO$2, Math.min(MAX_CALMAR_RATIO$2, expectedYearlyReturns / equityMaxDrawdown))
+            : null;
+        // Recovery Factor: numerator must be the compounded total return (equityFinal − 1) × 100,
+        // not the arithmetic totalPnl — denominator (equityMaxDrawdown) is from the compounded
+        // curve, so mixing units would inflate Recovery on long winning streaks.
+        // Null below MIN_SIGNALS_FOR_RATIOS — same sample-size gate as the other ratios,
+        // so a 3-trade run doesn't surface a Recovery Factor while Sharpe/Calmar are N/A.
+        // Null when account is blown — ratio is meaningless after total loss.
+        // Same MAX_CALMAR_RATIO clamp as Calmar — both are compounded-profit/DD ratios
+        // and explode the same way when DD is near zero.
+        const recoveryFactor = !canComputeRatios || blown || equityMaxDrawdown <= 0
+            ? null
+            : Math.max(-MAX_CALMAR_RATIO$2, Math.min(MAX_CALMAR_RATIO$2, ((equityFinal - 1) * 100) / equityMaxDrawdown));
         return {
             signalList: this._signalList,
             totalSignals,
             winCount,
             lossCount,
-            winRate: isUnsafe$3(winRate) ? null : winRate,
-            avgPnl: isUnsafe$3(avgPnl) ? null : avgPnl,
-            totalPnl: isUnsafe$3(totalPnl) ? null : totalPnl,
-            stdDev: isUnsafe$3(stdDev) ? null : stdDev,
-            sharpeRatio: isUnsafe$3(sharpeRatio) ? null : sharpeRatio,
-            annualizedSharpeRatio: isUnsafe$3(annualizedSharpeRatio) ? null : annualizedSharpeRatio,
-            certaintyRatio: isUnsafe$3(certaintyRatio) ? null : certaintyRatio,
-            expectedYearlyReturns: isUnsafe$3(expectedYearlyReturns) ? null : expectedYearlyReturns,
-            avgPeakPnl: isUnsafe$3(avgPeakPnl) ? null : avgPeakPnl,
-            avgFallPnl: isUnsafe$3(avgFallPnl) ? null : avgFallPnl,
-            sortinoRatio: isUnsafe$3(sortinoRatio) ? null : sortinoRatio,
-            calmarRatio: isUnsafe$3(calmarRatio) ? null : calmarRatio,
-            recoveryFactor: isUnsafe$3(recoveryFactor) ? null : recoveryFactor,
+            winRate: isUnsafe$4(winRate) ? null : winRate,
+            avgPnl: isUnsafe$4(avgPnl) ? null : avgPnl,
+            totalPnl: isUnsafe$4(totalPnl) ? null : totalPnl,
+            stdDev: isUnsafe$4(stdDev) ? null : stdDev,
+            sharpeRatio: isUnsafe$4(sharpeRatio) ? null : sharpeRatio,
+            annualizedSharpeRatio: isUnsafe$4(annualizedSharpeRatio) ? null : annualizedSharpeRatio,
+            certaintyRatio: isUnsafe$4(certaintyRatio) ? null : certaintyRatio,
+            expectedYearlyReturns: isUnsafe$4(expectedYearlyReturns) ? null : expectedYearlyReturns,
+            avgPeakPnl: isUnsafe$4(avgPeakPnl) ? null : avgPeakPnl,
+            avgFallPnl: isUnsafe$4(avgFallPnl) ? null : avgFallPnl,
+            sortinoRatio: isUnsafe$4(sortinoRatio) ? null : sortinoRatio,
+            calmarRatio: isUnsafe$4(calmarRatio) ? null : calmarRatio,
+            recoveryFactor: isUnsafe$4(recoveryFactor) ? null : recoveryFactor,
         };
     }
     /**
@@ -23871,24 +24023,26 @@ let ReportStorage$a = class ReportStorage {
             `**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)`}`,
             `**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, theoretical)`}`,
+            `**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)`}`,
-            `**Expected Yearly Returns:** ${stats.expectedYearlyReturns === null ? "N/A" : `${stats.expectedYearlyReturns > 0 ? "+" : ""}${stats.expectedYearlyReturns.toFixed(2)}% (higher is better, theoretical)`}`,
+            `**Expected Yearly Returns:** ${stats.expectedYearlyReturns === null ? "N/A" : `${stats.expectedYearlyReturns > 0 ? "+" : ""}${stats.expectedYearlyReturns.toFixed(2)}% (higher is better)`}`,
             `**Avg Peak PNL:** ${stats.avgPeakPnl === null ? "N/A" : `${stats.avgPeakPnl > 0 ? "+" : ""}${stats.avgPeakPnl.toFixed(2)}% (higher is better)`}`,
             `**Avg Max Drawdown PNL:** ${stats.avgFallPnl === null ? "N/A" : `${stats.avgFallPnl.toFixed(2)}% (closer to 0 is better)`}`,
             `**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, theoretical)`}`,
+            `**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)`}`,
             "",
             `*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.*`,
-            `*Annualized Sharpe Ratio: theoretical maximum assuming continuous trading. Real-world value is lower due to idle periods.*`,
-            `*Sortino Ratio: below 1.0 is poor, 1.0-2.0 is acceptable, above 2.0 is strong. Requires 30+ signals.*`,
+            `*Annualized Sharpe Ratio: per-trade Sharpe × √tradesPerYear; tradesPerYear = signals × 365 / calendarSpanDays. N/A unless ≥${MIN_SIGNALS_FOR_ANNUALIZATION$2} signals and span ≥${MIN_CALENDAR_SPAN_DAYS$2} days. Assumes returns are iid — autocorrelated strategies are overstated.*`,
+            `*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: theoretical maximum assuming all capital is deployed continuously with no idle time.*`,
-            `*Calmar Ratio: below 0.5 is poor, 0.5-1.0 is acceptable, above 1.0 is strong. Based on theoretical yearly returns.*`,
-            `*Recovery Factor: below 1.0 means total profit does not cover max drawdown. Above 3.0 is considered good.*`,
-            `*All metrics require 100+ signals to be statistically reliable. Time period matters only for Annualized Sharpe Ratio and Expected Yearly Returns — they assume current market conditions hold year-round, which may not reflect reality.*`,
+            `*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.*`,
+            `*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.*`,
         ].join("\n");
     }
     /**
@@ -24200,7 +24354,7 @@ const CREATE_FILE_NAME_FN$b = (symbol, strategyName, exchangeName, frameName, ti
  * @param value - Value to check
  * @returns true if value is unsafe, false otherwise
  */
-function isUnsafe$2(value) {
+function isUnsafe$3(value) {
     if (typeof value !== "number") {
         return true;
     }
@@ -24212,6 +24366,25 @@ function isUnsafe$2(value) {
     }
     return false;
 }
+/** Minimum closed signals required to annualize Sharpe / yearly returns / Calmar. */
+const MIN_SIGNALS_FOR_ANNUALIZATION$1 = 10;
+/** Minimum signals required for ANY ratio metric (Sharpe / Sortino / stdDev). Below this,
+ *  sample size is too small to estimate variance meaningfully. */
+const MIN_SIGNALS_FOR_RATIOS$1 = 10;
+/** Minimum calendar span (days) for trade-frequency extrapolation. */
+const MIN_CALENDAR_SPAN_DAYS$1 = 14;
+/** Hard cap on tradesPerYear — prevents absurd extrapolation from short windows / clustered trades. */
+const MAX_TRADES_PER_YEAR$1 = 365;
+/** Hard cap on |expectedYearlyReturns| percent. Compound interest on high avgPnl × frequency
+ *  blows up to mathematically correct but business-unrealistic values. ±100% = 2x equity —
+ *  anything above this we suspect is a noisy estimate, not a genuine edge. Above the cap → null. */
+const MAX_EXPECTED_YEARLY_RETURNS$1 = 100;
+/** Hard cap on |calmarRatio|. Prevents explosion when equityMaxDrawdown is near zero. */
+const MAX_CALMAR_RATIO$1 = 1000;
+/** Minimum stdDev required for Sharpe/Sortino. Identical-returns series produce
+ *  float-artifact stdDev (~1e-17) that's > 0 but spuriously inflates sharpe to
+ *  astronomical magnitudes (avgPnl / epsilon). */
+const STDDEV_EPSILON$1 = 1e-9;
 /**
  * Storage class for accumulating all tick events per strategy.
  * Maintains a chronological list of all events (idle, opened, active, closed).
@@ -24495,84 +24668,190 @@ let ReportStorage$9 = class ReportStorage {
             };
         }
         const closedEvents = this._eventList.filter((e) => e.action === "closed");
-        const totalClosed = closedEvents.length;
-        const winCount = closedEvents.filter((e) => e.pnl && e.pnl > 0).length;
-        const lossCount = closedEvents.filter((e) => e.pnl && e.pnl < 0).length;
-        // Calculate basic statistics
-        const avgPnl = totalClosed > 0
-            ? closedEvents.reduce((sum, e) => sum + (e.pnl || 0), 0) / totalClosed
+        // Valid closed set — single source of truth. Events must have numeric pnl AND valid
+        // timestamps. Win/loss counts, returns, calendar span, equity curve — all derived
+        // from this set so they cannot disagree.
+        const validClosed = closedEvents.filter((e) => typeof e.pnl === "number" &&
+            typeof e.timestamp === "number" &&
+            e.timestamp > 0 &&
+            typeof (e.pendingAt ?? e.timestamp) === "number");
+        const totalClosed = validClosed.length;
+        const winCount = validClosed.filter((e) => e.pnl > 0).length;
+        const lossCount = validClosed.filter((e) => e.pnl < 0).length;
+        const returns = validClosed.map((e) => e.pnl);
+        const avgPnl = returns.length > 0
+            ? returns.reduce((sum, r) => sum + r, 0) / returns.length
             : 0;
-        const totalPnl = closedEvents.reduce((sum, e) => sum + (e.pnl || 0), 0);
-        const winRate = (winCount / totalClosed) * 100;
-        // Calculate Sharpe Ratio (risk-free rate = 0)
-        let sharpeRatio = 0;
-        let stdDev = 0;
-        if (totalClosed > 0) {
-            const returns = closedEvents.map((e) => e.pnl || 0);
-            const variance = returns.reduce((sum, r) => sum + Math.pow(r - avgPnl, 2), 0) / totalClosed;
-            stdDev = Math.sqrt(variance);
-            sharpeRatio = stdDev > 0 ? avgPnl / stdDev : 0;
-        }
-        const annualizedSharpeRatio = sharpeRatio * Math.sqrt(365);
-        // Calculate Certainty Ratio
-        let certaintyRatio = 0;
-        if (totalClosed > 0) {
-            const wins = closedEvents.filter((e) => e.pnl && e.pnl > 0);
-            const losses = closedEvents.filter((e) => e.pnl && e.pnl < 0);
+        const totalPnl = returns.reduce((sum, r) => sum + r, 0);
+        // Win rate excludes break-even trades from both numerator and denominator.
+        const decisiveTrades = winCount + lossCount;
+        const winRate = decisiveTrades > 0 ? (winCount / decisiveTrades) * 100 : 0;
+        // Trade frequency from calendar span — gated by minimum span and sample size to
+        // suppress absurd annualization on short / sparse runs. Span built from validClosed
+        // so denominator (calendarSpanDays) and numerator (returns.length) come from the
+        // same event set.
+        let firstPendingAt = Infinity;
+        let lastCloseAt = -Infinity;
+        for (const e of validClosed) {
+            const startAt = e.pendingAt ?? e.timestamp;
+            if (startAt < firstPendingAt)
+                firstPendingAt = startAt;
+            if (e.timestamp > lastCloseAt)
+                lastCloseAt = e.timestamp;
+        }
+        const calendarSpanDays = validClosed.length > 0
+            ? (lastCloseAt - firstPendingAt) / (1000 * 60 * 60 * 24)
+            : 0;
+        // tradesPerYear uses the RAW observed frequency — no clipping. Clipping would
+        // silently understate Sharpe / Calmar / expectedYearlyReturns. Instead, if the
+        // raw frequency exceeds MAX_TRADES_PER_YEAR we treat the sample as too clustered
+        // for reliable annualization and surface every annualized metric as null.
+        const rawTradesPerYear = returns.length >= MIN_SIGNALS_FOR_ANNUALIZATION$1 &&
+            calendarSpanDays >= MIN_CALENDAR_SPAN_DAYS$1
+            ? (returns.length / calendarSpanDays) * 365
+            : 0;
+        const canAnnualize = rawTradesPerYear > 0 && rawTradesPerYear <= MAX_TRADES_PER_YEAR$1;
+        const tradesPerYear = canAnnualize ? rawTradesPerYear : 0;
+        // Per-trade Sharpe Ratio (risk-free rate = 0). Sample stddev (N-1).
+        // Per-trade ratios are gated by MIN_SIGNALS_FOR_RATIOS — below that, variance estimates
+        // are too noisy to publish (high chance of spurious ±Sharpe).
+        const canComputeRatios = returns.length >= MIN_SIGNALS_FOR_RATIOS$1;
+        const stdDev = canComputeRatios
+            ? Math.sqrt(returns.reduce((sum, r) => sum + Math.pow(r - avgPnl, 2), 0) / (returns.length - 1))
+            : 0;
+        // STDDEV_EPSILON guard — protects against float-artifact stdDev from identical
+        // returns producing spuriously astronomical sharpe.
+        const sharpeRatio = canComputeRatios && stdDev > STDDEV_EPSILON$1
+            ? avgPnl / stdDev
+            : null;
+        // Annualize only when gate passes; otherwise null.
+        const annualizedSharpeRatio = canAnnualize && sharpeRatio !== null
+            ? sharpeRatio * Math.sqrt(tradesPerYear)
+            : null;
+        // Certainty Ratio: null (not zero) when there are no losing trades — a flawless
+        // strategy has undefined Certainty Ratio, not "worst case zero". Computed on
+        // validClosed for consistency with other ratios.
+        // Gated below MIN_SIGNALS_FOR_RATIOS — same sample-size gate as Sharpe/Sortino,
+        // so the report doesn't surface certainty on a handful of trades while
+        // withholding the rest.
+        let certaintyRatio = null;
+        if (canComputeRatios && totalClosed > 0) {
+            const wins = validClosed.filter((e) => e.pnl > 0);
+            const losses = validClosed.filter((e) => e.pnl < 0);
             const avgWin = wins.length > 0
-                ? wins.reduce((sum, e) => sum + (e.pnl || 0), 0) / wins.length
+                ? wins.reduce((sum, e) => sum + e.pnl, 0) / wins.length
                 : 0;
             const avgLoss = losses.length > 0
-                ? losses.reduce((sum, e) => sum + (e.pnl || 0), 0) / losses.length
+                ? losses.reduce((sum, e) => sum + e.pnl, 0) / losses.length
                 : 0;
-            certaintyRatio = avgLoss < 0 ? avgWin / Math.abs(avgLoss) : 0;
-        }
-        // Calculate Expected Yearly Returns
-        let expectedYearlyReturns = 0;
-        if (totalClosed > 0) {
-            const avgDurationMin = closedEvents.reduce((sum, e) => sum + (e.duration || 0), 0) / totalClosed;
-            const avgDurationDays = avgDurationMin / (60 * 24);
-            const tradesPerYear = avgDurationDays > 0 ? 365 / avgDurationDays : 0;
-            expectedYearlyReturns = avgPnl * tradesPerYear;
-        }
-        const avgPeakPnl = totalClosed > 0
-            ? closedEvents.reduce((sum, e) => sum + (e.peakPnl || 0), 0) / totalClosed
-            : 0;
-        const avgFallPnl = totalClosed > 0
-            ? closedEvents.reduce((sum, e) => sum + (e.fallPnl || 0), 0) / totalClosed
-            : 0;
-        // Downside per signal: fallPnl captures the worst intra-trade dip (maxDrawdown.pnlPercentage)
-        const fallReturns = closedEvents.map((e) => e.fallPnl || 0);
-        // Calculate Sortino Ratio: avgPnl / stdDev(maxDrawdown per signal)
-        let sortinoRatio = 0;
-        if (totalClosed > 0) {
-            const fallVariance = fallReturns.reduce((sum, r) => sum + Math.pow(r, 2), 0) / totalClosed;
-            const fallDeviation = Math.sqrt(fallVariance);
-            sortinoRatio = fallDeviation > 0 ? avgPnl / fallDeviation : 0;
-        }
-        // Max absolute drawdown across all signals — denominator for Calmar and Recovery
-        const maxAbsFall = fallReturns.reduce((max, r) => Math.max(max, Math.abs(r)), 0);
-        const calmarRatio = maxAbsFall > 0 ? expectedYearlyReturns / maxAbsFall : 0;
-        const recoveryFactor = maxAbsFall > 0 ? totalPnl / maxAbsFall : 0;
+            // STDDEV_EPSILON guard on |avgLoss| protects against float-artifact
+            // losses producing spurious astronomical certaintyRatio.
+            certaintyRatio = Math.abs(avgLoss) > STDDEV_EPSILON$1 && avgLoss < 0
+                ? avgWin / Math.abs(avgLoss)
+                : null;
+        }
+        // Average only over signals that have the value — do not dilute the mean with zeros.
+        // Use validClosed to keep all metric denominators consistent.
+        const peakValues = validClosed
+            .map((e) => e.peakPnl)
+            .filter((v) => typeof v === "number");
+        const fallValues = validClosed
+            .map((e) => e.fallPnl)
+            .filter((v) => typeof v === "number");
+        const avgPeakPnl = peakValues.length > 0
+            ? peakValues.reduce((sum, v) => sum + v, 0) / peakValues.length
+            : null;
+        const avgFallPnl = fallValues.length > 0
+            ? fallValues.reduce((sum, v) => sum + v, 0) / fallValues.length
+            : null;
+        // Sortino (canonical, Sortino 1991): (avgPnl - MAR) / downside deviation, where
+        // downsideDev = √( Σ min(0, r - MAR)² / N_total ). We use MAR = 0 (risk-free target),
+        // so the numerator reduces to avgPnl and the squared term to r² for r < 0.
+        // Dividing by N_total (not N_negative) properly penalises strategies with frequent
+        // losses; the "modified" form (N_negative) hides frequency risk in catastrophic-tail
+        // strategies.
+        const sortinoRatio = (() => {
+            if (!canComputeRatios)
+                return null;
+            const negativeReturns = returns.filter((r) => r < 0);
+            if (negativeReturns.length === 0)
+                return null;
+            const downsideVariance = negativeReturns.reduce((sum, r) => sum + r * r, 0) / returns.length;
+            const downsideDeviation = Math.sqrt(downsideVariance);
+            // Same epsilon guard as Sharpe — protects against float-artifact downsideDev.
+            return downsideDeviation > STDDEV_EPSILON$1 ? avgPnl / downsideDeviation : null;
+        })();
+        // Equity-curve max drawdown via compounded equity (multiplicative). Returns are per-trade
+        // 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 = [];
+        for (let i = validClosed.length - 1; i >= 0; i--) {
+            chronologicalReturns.push(validClosed[i].pnl);
+        }
+        let equity = 1;
+        let peak = 1;
+        let equityMaxDrawdown = 0;
+        let blown = false;
+        for (const r of chronologicalReturns) {
+            equity *= 1 + r / 100;
+            if (equity <= 0) {
+                equityMaxDrawdown = 100;
+                blown = true;
+                break;
+            }
+            if (equity > peak)
+                peak = equity;
+            const dd = (peak - equity) / peak * 100;
+            if (dd > equityMaxDrawdown)
+                equityMaxDrawdown = dd;
+        }
+        const equityFinal = blown ? 0 : equity;
+        // Compounded yearly return via geometric mean of equity curve:
+        // equityFinal^(tradesPerYear / N) - 1 — accounts for volatility drag.
+        // If account is blown, full loss. If raw value exceeds MAX_EXPECTED_YEARLY_RETURNS,
+        // return null rather than showing the cap — capped numbers mislead users.
+        const expectedYearlyReturns = canAnnualize
+            ? blown
+                ? -100
+                : (() => {
+                    const raw = (Math.pow(equityFinal, tradesPerYear / returns.length) - 1) * 100;
+                    return Math.abs(raw) > MAX_EXPECTED_YEARLY_RETURNS$1 ? null : raw;
+                })()
+            : null;
+        // Calmar — cap |value| at MAX_CALMAR_RATIO to prevent explosion when DD is near zero.
+        const calmarRatio = equityMaxDrawdown > 0 && expectedYearlyReturns !== null
+            ? Math.max(-MAX_CALMAR_RATIO$1, Math.min(MAX_CALMAR_RATIO$1, expectedYearlyReturns / equityMaxDrawdown))
+            : null;
+        // Recovery Factor: numerator must be the compounded total return, not arithmetic totalPnl —
+        // denominator is from the compounded equity curve, so mixing units inflates Recovery.
+        // Null below MIN_SIGNALS_FOR_RATIOS — same sample-size gate as the other ratios,
+        // so a 3-trade run doesn't surface a Recovery Factor while Sharpe/Calmar are N/A.
+        // Null when account is blown.
+        // Same MAX_CALMAR_RATIO clamp as Calmar — both are compounded-profit/DD ratios
+        // and explode the same way when DD is near zero.
+        const recoveryFactor = !canComputeRatios || blown || equityMaxDrawdown <= 0
+            ? null
+            : Math.max(-MAX_CALMAR_RATIO$1, Math.min(MAX_CALMAR_RATIO$1, ((equityFinal - 1) * 100) / equityMaxDrawdown));
         return {
             eventList: this._eventList,
             totalEvents: this._eventList.length,
             totalClosed,
             winCount,
             lossCount,
-            winRate: isUnsafe$2(winRate) ? null : winRate,
-            avgPnl: isUnsafe$2(avgPnl) ? null : avgPnl,
-            totalPnl: isUnsafe$2(totalPnl) ? null : totalPnl,
-            stdDev: isUnsafe$2(stdDev) ? null : stdDev,
-            sharpeRatio: isUnsafe$2(sharpeRatio) ? null : sharpeRatio,
-            annualizedSharpeRatio: isUnsafe$2(annualizedSharpeRatio) ? null : annualizedSharpeRatio,
-            certaintyRatio: isUnsafe$2(certaintyRatio) ? null : certaintyRatio,
-            expectedYearlyReturns: isUnsafe$2(expectedYearlyReturns) ? null : expectedYearlyReturns,
-            avgPeakPnl: isUnsafe$2(avgPeakPnl) ? null : avgPeakPnl,
-            avgFallPnl: isUnsafe$2(avgFallPnl) ? null : avgFallPnl,
-            sortinoRatio: isUnsafe$2(sortinoRatio) ? null : sortinoRatio,
-            calmarRatio: isUnsafe$2(calmarRatio) ? null : calmarRatio,
-            recoveryFactor: isUnsafe$2(recoveryFactor) ? null : recoveryFactor,
+            winRate: isUnsafe$3(winRate) ? null : winRate,
+            avgPnl: isUnsafe$3(avgPnl) ? null : avgPnl,
+            totalPnl: isUnsafe$3(totalPnl) ? null : totalPnl,
+            stdDev: isUnsafe$3(stdDev) ? null : stdDev,
+            sharpeRatio: isUnsafe$3(sharpeRatio) ? null : sharpeRatio,
+            annualizedSharpeRatio: isUnsafe$3(annualizedSharpeRatio) ? null : annualizedSharpeRatio,
+            certaintyRatio: isUnsafe$3(certaintyRatio) ? null : certaintyRatio,
+            expectedYearlyReturns: isUnsafe$3(expectedYearlyReturns) ? null : expectedYearlyReturns,
+            avgPeakPnl: isUnsafe$3(avgPeakPnl) ? null : avgPeakPnl,
+            avgFallPnl: isUnsafe$3(avgFallPnl) ? null : avgFallPnl,
+            sortinoRatio: isUnsafe$3(sortinoRatio) ? null : sortinoRatio,
+            calmarRatio: isUnsafe$3(calmarRatio) ? null : calmarRatio,
+            recoveryFactor: isUnsafe$3(recoveryFactor) ? null : recoveryFactor,
         };
     }
     /**
@@ -24620,18 +24899,20 @@ let ReportStorage$9 = class ReportStorage {
             `**Avg Peak PNL:** ${stats.avgPeakPnl === null ? "N/A" : `${stats.avgPeakPnl > 0 ? "+" : ""}${stats.avgPeakPnl.toFixed(2)}% (higher is better)`}`,
             `**Avg Max Drawdown PNL:** ${stats.avgFallPnl === null ? "N/A" : `${stats.avgFallPnl.toFixed(2)}% (closer to 0 is better)`}`,
             `**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, theoretical)`}`,
+            `**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)`}`,
             "",
             `*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.*`,
-            `*Annualized Sharpe Ratio: theoretical maximum assuming continuous trading. Real-world value is lower due to idle periods.*`,
-            `*Sortino Ratio: below 1.0 is poor, 1.0-2.0 is acceptable, above 2.0 is strong. Requires 30+ signals.*`,
+            `*Annualized Sharpe Ratio: per-trade Sharpe × √tradesPerYear; tradesPerYear = signals × 365 / calendarSpanDays. N/A unless ≥${MIN_SIGNALS_FOR_ANNUALIZATION$1} signals and span ≥${MIN_CALENDAR_SPAN_DAYS$1} days. Assumes returns are iid — autocorrelated strategies are overstated.*`,
+            `*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: theoretical maximum assuming all capital is deployed continuously with no idle time.*`,
-            `*Calmar Ratio: below 0.5 is poor, 0.5-1.0 is acceptable, above 1.0 is strong. Based on theoretical yearly returns.*`,
-            `*Recovery Factor: below 1.0 means total profit does not cover max drawdown. Above 3.0 is considered good.*`,
-            `*All metrics require 100+ signals to be statistically reliable. Time period matters only for Annualized Sharpe Ratio and Expected Yearly Returns — they assume current market conditions hold year-round, which may not reflect reality.*`,
+            `*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.*`,
+            `*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.*`,
         ].join("\n");
     }
     /**
@@ -25010,7 +25291,9 @@ let ReportStorage$8 = class ReportStorage {
      */
     addOpenedEvent(data) {
         const durationMs = data.signal.pendingAt - data.signal.scheduledAt;
-        const durationMin = Math.round(durationMs / 60000);
+        // Keep fractional minutes — rounding to whole minutes zeroed out sub-30s durations,
+        // which dragged high-frequency averages towards zero.
+        const durationMin = durationMs / 60000;
         const newEvent = {
             timestamp: data.signal.pendingAt,
             action: "opened",
@@ -25046,7 +25329,8 @@ let ReportStorage$8 = class ReportStorage {
      */
     addCancelledEvent(data) {
         const durationMs = data.closeTimestamp - data.signal.scheduledAt;
-        const durationMin = Math.round(durationMs / 60000);
+        // Keep fractional minutes — rounding to whole minutes zeroed out sub-30s durations.
+        const durationMin = durationMs / 60000;
         const newEvent = {
             timestamp: data.closeTimestamp,
             action: "cancelled",
@@ -25102,19 +25386,33 @@ let ReportStorage$8 = class ReportStorage {
         const totalScheduled = scheduledEvents.length;
         const totalOpened = openedEvents.length;
         const totalCancelled = cancelledEvents.length;
-        // Calculate cancellation rate
-        const cancellationRate = totalScheduled > 0 ? (totalCancelled / totalScheduled) * 100 : null;
-        // Calculate activation rate
-        const activationRate = totalScheduled > 0 ? (totalOpened / totalScheduled) * 100 : null;
-        // Calculate average wait time for cancelled signals
-        const avgWaitTime = totalCancelled > 0
-            ? cancelledEvents.reduce((sum, e) => sum + (e.duration || 0), 0) /
-                totalCancelled
+        // Rate denominators must include only scheduled events whose outcome (opened/cancelled)
+        // is also in the buffer. Otherwise a sliding window of 250 entries can drop the
+        // "scheduled" record before its outcome arrives, inflating rates above 100% or
+        // causing one rate to fire without the other. Match by signalId.
+        const scheduledIds = new Set(scheduledEvents.map((e) => e.signalId).filter((id) => typeof id === "string"));
+        const openedFromScheduled = openedEvents.filter((e) => typeof e.signalId === "string" && scheduledIds.has(e.signalId));
+        const cancelledFromScheduled = cancelledEvents.filter((e) => typeof e.signalId === "string" && scheduledIds.has(e.signalId));
+        const resolvedScheduled = openedFromScheduled.length + cancelledFromScheduled.length;
+        const cancellationRate = resolvedScheduled > 0
+            ? (cancelledFromScheduled.length / resolvedScheduled) * 100
+            : null;
+        const activationRate = resolvedScheduled > 0
+            ? (openedFromScheduled.length / resolvedScheduled) * 100
+            : null;
+        // Average durations — include only events with a numeric duration, do not dilute
+        // the mean with zeros for missing values.
+        const cancelledDurations = cancelledEvents
+            .map((e) => e.duration)
+            .filter((d) => typeof d === "number");
+        const openedDurations = openedEvents
+            .map((e) => e.duration)
+            .filter((d) => typeof d === "number");
+        const avgWaitTime = cancelledDurations.length > 0
+            ? cancelledDurations.reduce((sum, d) => sum + d, 0) / cancelledDurations.length
             : null;
-        // Calculate average activation time for opened signals
-        const avgActivationTime = totalOpened > 0
-            ? openedEvents.reduce((sum, e) => sum + (e.duration || 0), 0) /
-                totalOpened
+        const avgActivationTime = openedDurations.length > 0
+            ? openedDurations.reduce((sum, d) => sum + d, 0) / openedDurations.length
             : null;
         return {
             eventList: this._eventList,
@@ -25161,13 +25459,15 @@ let ReportStorage$8 = class ReportStorage {
             table,
             "",
             `**Total events:** ${stats.totalEvents}`,
-            `**Scheduled signals:** ${stats.totalScheduled}`,
+            `**Scheduled signals (raw):** ${stats.totalScheduled}`,
             `**Opened signals:** ${stats.totalOpened}`,
             `**Cancelled signals:** ${stats.totalCancelled}`,
             `**Activation rate:** ${stats.activationRate === null ? "N/A" : `${stats.activationRate.toFixed(2)}% (higher is better)`}`,
             `**Cancellation rate:** ${stats.cancellationRate === null ? "N/A" : `${stats.cancellationRate.toFixed(2)}% (lower is better)`}`,
             `**Average activation time:** ${stats.avgActivationTime === null ? "N/A" : `${stats.avgActivationTime.toFixed(2)} minutes`}`,
-            `**Average wait time (cancelled):** ${stats.avgWaitTime === null ? "N/A" : `${stats.avgWaitTime.toFixed(2)} minutes`}`
+            `**Average wait time (cancelled):** ${stats.avgWaitTime === null ? "N/A" : `${stats.avgWaitTime.toFixed(2)} minutes`}`,
+            "",
+            `*Activation / Cancellation rates are computed over scheduled signals whose outcome (opened or cancelled) is also in the buffer — matched by signalId. "Scheduled signals (raw)" above is the unmatched count and may include records whose outcome has not yet arrived or was evicted from the buffer.*`
         ].join("\n");
     }
     /**
@@ -25472,13 +25772,37 @@ const CREATE_FILE_NAME_FN$9 = (symbol, strategyName, exchangeName, frameName, ti
     return `${parts.join("_")}-${timestamp}.md`;
 };
 /**
- * Calculates percentile value from sorted array.
+ * Checks if a value is unsafe for display (not a number, NaN, or Infinity).
+ */
+function isUnsafe$2(value) {
+    if (typeof value !== "number") {
+        return true;
+    }
+    if (isNaN(value)) {
+        return true;
+    }
+    if (!isFinite(value)) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Calculates percentile value from sorted array using linear interpolation
+ * between adjacent ranks (equivalent to numpy.percentile with default linear method).
+ * Falls back to nearest-rank for length 0/1.
  */
 function percentile(sortedArray, p) {
     if (sortedArray.length === 0)
         return 0;
-    const index = Math.ceil((sortedArray.length * p) / 100) - 1;
-    return sortedArray[Math.max(0, index)];
+    if (sortedArray.length === 1)
+        return sortedArray[0];
+    const rank = (p / 100) * (sortedArray.length - 1);
+    const lower = Math.floor(rank);
+    const upper = Math.ceil(rank);
+    if (lower === upper)
+        return sortedArray[lower];
+    const fraction = rank - lower;
+    return sortedArray[lower] * (1 - fraction) + sortedArray[upper] * fraction;
 }
 /**
  * Storage class for accumulating performance metrics per strategy.
@@ -25534,10 +25858,12 @@ class PerformanceStorage {
             const durations = events.map((e) => e.duration).sort((a, b) => a - b);
             const totalDuration = durations.reduce((sum, d) => sum + d, 0);
             const avgDuration = totalDuration / durations.length;
-            // Calculate standard deviation
-            const variance = durations.reduce((sum, d) => sum + Math.pow(d - avgDuration, 2), 0) /
-                durations.length;
-            const stdDev = Math.sqrt(variance);
+            // Sample standard deviation (Bessel correction: divide by N-1, not N) — consistent
+            // with Sharpe/Sortino calculations in Backtest/Live/Heat services.
+            const stdDev = durations.length > 1
+                ? Math.sqrt(durations.reduce((sum, d) => sum + Math.pow(d - avgDuration, 2), 0) /
+                    (durations.length - 1))
+                : 0;
             // Calculate wait times between events
             const waitTimes = [];
             for (let i = 0; i < events.length; i++) {
@@ -25610,9 +25936,13 @@ class PerformanceStorage {
         const rows = await Promise.all(sortedMetrics.map(async (metric, index) => Promise.all(visibleColumns.map((col) => col.format(metric, index)))));
         const tableData = [header, separator, ...rows];
         const summaryTable = tableData.map((row) => `| ${row.join(" | ")} |`).join("\n");
-        // Calculate percentage of total time for each metric
+        // Calculate percentage of total time for each metric. Guard against zero total
+        // duration (all-instant operations) to avoid NaN% in the rendered report.
         const percentages = sortedMetrics.map((metric) => {
-            const pct = (metric.totalDuration / stats.totalDuration) * 100;
+            const pctRaw = stats.totalDuration > 0
+                ? (metric.totalDuration / stats.totalDuration) * 100
+                : 0;
+            const pct = isUnsafe$2(pctRaw) ? 0 : pctRaw;
             return `- **${metric.metricType}**: ${pct.toFixed(1)}% (${metric.totalDuration.toFixed(2)}ms total)`;
         });
         return [
@@ -26381,6 +26711,25 @@ function isUnsafe(value) {
     }
     return false;
 }
+/** Minimum closed signals required to annualize Sharpe / yearly returns / Calmar. */
+const MIN_SIGNALS_FOR_ANNUALIZATION = 10;
+/** Minimum signals required for ANY ratio metric (Sharpe / Sortino / stdDev). Below this,
+ *  sample size is too small to estimate variance meaningfully. */
+const MIN_SIGNALS_FOR_RATIOS = 10;
+/** Minimum calendar span (days) for trade-frequency extrapolation. */
+const MIN_CALENDAR_SPAN_DAYS = 14;
+/** Hard cap on tradesPerYear — prevents absurd extrapolation from short windows / clustered trades. */
+const MAX_TRADES_PER_YEAR = 365;
+/** Hard cap on |expectedYearlyReturns| percent. Compound interest on high avgPnl × frequency
+ *  blows up to mathematically correct but business-unrealistic values. ±100% = 2x equity —
+ *  anything above this we suspect is a noisy estimate, not a genuine edge. Above the cap → null. */
+const MAX_EXPECTED_YEARLY_RETURNS = 100;
+/** Hard cap on |calmarRatio|. Prevents explosion when equityMaxDrawdown is near zero. */
+const MAX_CALMAR_RATIO = 1000;
+/** Minimum stdDev required for Sharpe/Sortino. Identical-returns series produce
+ *  float-artifact stdDev (~1e-17) that's > 0 but spuriously inflates sharpe to
+ *  astronomical magnitudes (avgPnl / epsilon). */
+const STDDEV_EPSILON = 1e-9;
 /**
  * Storage class for accumulating closed signals per strategy and generating heatmap.
  * Maintains symbol-level statistics and provides portfolio-wide metrics.
@@ -26422,7 +26771,7 @@ class HeatmapStorage {
      * - **totalPnl** — sum of `pnlPercentage` across all signals
      * - **avgPnl** — arithmetic mean of `pnlPercentage`
      * - **stdDev** — population standard deviation of `pnlPercentage`
-     * - **sharpeRatio** — `avgPnl / stdDev`; requires ≥ 2 signals and `stdDev > 0`
+     * - **sharpeRatio** — per-trade Sharpe: `avgPnl / stdDev`; requires ≥ 2 signals and `stdDev > 0`
      * - **maxDrawdown** — largest cumulative loss streak (absolute value of peak negative equity)
      * - **profitFactor** — `sumWins / |sumLosses|`; requires at least one win and one loss
      * - **avgWin / avgLoss** — mean of positive / negative trades respectively
@@ -26438,10 +26787,12 @@ class HeatmapStorage {
         const totalTrades = signals.length;
         const winCount = signals.filter((s) => s.pnl.pnlPercentage > 0).length;
         const lossCount = signals.filter((s) => s.pnl.pnlPercentage < 0).length;
-        // Calculate win rate
+        // Win rate excludes break-even trades from both numerator and denominator —
+        // they are neither wins nor losses.
         let winRate = null;
-        if (totalTrades > 0) {
-            winRate = (winCount / totalTrades) * 100;
+        const decisiveTrades = winCount + lossCount;
+        if (decisiveTrades > 0) {
+            winRate = (winCount / decisiveTrades) * 100;
         }
         // Calculate total PNL
         let totalPnl = null;
@@ -26453,36 +26804,47 @@ class HeatmapStorage {
         if (signals.length > 0) {
             avgPnl = totalPnl / signals.length;
         }
-        // Calculate standard deviation
+        // Sample standard deviation (Bessel correction: divide by N-1, not N).
+        // Per-symbol ratios are gated by MIN_SIGNALS_FOR_RATIOS — variance estimates from
+        // tiny samples are too noisy to publish.
+        const canComputeRatios = signals.length >= MIN_SIGNALS_FOR_RATIOS;
         let stdDev = null;
-        if (signals.length > 1 && avgPnl !== null) {
-            const variance = signals.reduce((acc, s) => acc + Math.pow(s.pnl.pnlPercentage - avgPnl, 2), 0) / signals.length;
+        if (canComputeRatios && avgPnl !== null) {
+            const variance = signals.reduce((acc, s) => acc + Math.pow(s.pnl.pnlPercentage - avgPnl, 2), 0) / (signals.length - 1);
             stdDev = Math.sqrt(variance);
         }
-        // Calculate Sharpe Ratio
+        // Per-trade Sharpe Ratio
         let sharpeRatio = null;
-        if (avgPnl !== null && stdDev !== null && stdDev !== 0) {
+        // STDDEV_EPSILON guard — protects against float-artifact stdDev producing
+        // spuriously astronomical sharpe on identical-returns symbols.
+        if (avgPnl !== null && stdDev !== null && stdDev > STDDEV_EPSILON) {
             sharpeRatio = avgPnl / stdDev;
         }
-        // Calculate Maximum Drawdown
+        // 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.
         let maxDrawdown = null;
+        let equityFinal = 1;
+        let blown = false;
         if (signals.length > 0) {
-            let peak = 0;
-            let currentDrawdown = 0;
+            let equity = 1;
+            let peak = 1;
             let maxDD = 0;
-            for (const signal of signals) {
-                peak += signal.pnl.pnlPercentage;
-                if (peak > 0) {
-                    currentDrawdown = 0;
-                }
-                else {
-                    currentDrawdown = Math.abs(peak);
-                    if (currentDrawdown > maxDD) {
-                        maxDD = currentDrawdown;
-                    }
+            for (let i = signals.length - 1; i >= 0; i--) {
+                equity *= 1 + signals[i].pnl.pnlPercentage / 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;
             }
             maxDrawdown = maxDD;
+            equityFinal = blown ? 0 : equity;
         }
         // Calculate Profit Factor
         let profitFactor = null;
@@ -26493,7 +26855,9 @@ class HeatmapStorage {
             const sumLosses = Math.abs(signals
                 .filter((s) => s.pnl.pnlPercentage < 0)
                 .reduce((acc, s) => acc + s.pnl.pnlPercentage, 0));
-            if (sumLosses > 0) {
+            // STDDEV_EPSILON guard — float-artifact losses (≈1e-15) would otherwise
+            // produce spurious astronomical profitFactor (≈1e14).
+            if (sumLosses > STDDEV_EPSILON) {
                 profitFactor = sumWins / sumLosses;
             }
         }
@@ -26533,45 +26897,110 @@ class HeatmapStorage {
                 }
             }
         }
-        // Calculate Expectancy
+        // Expectancy — probabilities from observed win/loss counts (break-evens contribute 0).
         let expectancy = null;
-        if (winRate !== null && avgWin !== null && avgLoss !== null) {
-            const lossRate = 100 - winRate;
-            expectancy = (winRate / 100) * avgWin + (lossRate / 100) * avgLoss;
+        if (totalTrades > 0 && avgWin !== null && avgLoss !== null) {
+            const winProb = winCount / totalTrades;
+            const lossProb = lossCount / totalTrades;
+            expectancy = winProb * avgWin + lossProb * avgLoss;
         }
-        // Calculate average peak and fall PNL
+        else if (totalTrades > 0 && avgWin !== null && avgLoss === null) {
+            // No losing trades — expectancy is just average win frequency × avgWin
+            expectancy = (winCount / totalTrades) * avgWin;
+        }
+        else if (totalTrades > 0 && avgWin === null && avgLoss !== null) {
+            expectancy = (lossCount / totalTrades) * avgLoss;
+        }
+        // Average only over signals that have the value — do not dilute the mean with zeros.
         let avgPeakPnl = null;
         let avgFallPnl = null;
         if (signals.length > 0) {
-            avgPeakPnl = signals.reduce((acc, s) => acc + (s.signal.peakProfit?.pnlPercentage ?? 0), 0) / signals.length;
-            avgFallPnl = signals.reduce((acc, s) => acc + (s.signal.maxDrawdown?.pnlPercentage ?? 0), 0) / signals.length;
+            const peakValues = signals
+                .map((s) => s.signal.peakProfit?.pnlPercentage)
+                .filter((v) => typeof v === "number");
+            const fallValues = signals
+                .map((s) => s.signal.maxDrawdown?.pnlPercentage)
+                .filter((v) => typeof v === "number");
+            avgPeakPnl = peakValues.length > 0
+                ? peakValues.reduce((sum, v) => sum + v, 0) / peakValues.length
+                : null;
+            avgFallPnl = fallValues.length > 0
+                ? fallValues.reduce((sum, v) => sum + v, 0) / fallValues.length
+                : null;
         }
-        // Downside per signal: maxDrawdown.pnlPercentage captures the worst intra-trade dip
-        const fallReturns = signals.map((s) => s.signal.maxDrawdown?.pnlPercentage ?? 0);
-        // Calculate Sortino Ratio: avgPnl / stdDev(maxDrawdown per signal)
+        // Sortino (canonical, Sortino 1991): (avgPnl - MAR) / downside deviation, where
+        // downsideDev = √( Σ min(0, r - MAR)² / N_total ). We use MAR = 0 (risk-free target),
+        // so the numerator reduces to avgPnl and the squared term to r² for r < 0.
+        // Dividing by N_total (not N_negative) properly penalises strategies with frequent
+        // losses; the "modified" form (N_negative) hides frequency risk in catastrophic-tail
+        // strategies.
         let sortinoRatio = null;
-        if (signals.length > 0 && avgPnl !== null) {
-            const fallVariance = fallReturns.reduce((acc, r) => acc + Math.pow(r, 2), 0) / signals.length;
-            const fallDeviation = Math.sqrt(fallVariance);
-            if (fallDeviation > 0) {
-                sortinoRatio = avgPnl / fallDeviation;
-            }
-        }
-        // Max absolute drawdown across all signals — denominator for Calmar and Recovery
-        const maxAbsFall = fallReturns.reduce((max, r) => Math.max(max, Math.abs(r)), 0);
-        // Expected yearly returns — needed for Calmar
-        let expectedYearlyReturns = 0;
-        if (signals.length > 0 && avgPnl !== null) {
-            const avgDurationMs = signals.reduce((sum, s) => sum + (s.closeTimestamp - s.signal.pendingAt), 0) / signals.length;
-            const avgDurationDays = avgDurationMs / (1000 * 60 * 60 * 24);
-            const tradesPerYear = avgDurationDays > 0 ? 365 / avgDurationDays : 0;
-            expectedYearlyReturns = avgPnl * tradesPerYear;
+        if (canComputeRatios && avgPnl !== null) {
+            const negativeReturns = signals
+                .map((s) => s.pnl.pnlPercentage)
+                .filter((r) => r < 0);
+            if (negativeReturns.length > 0) {
+                const downsideVariance = negativeReturns.reduce((acc, r) => acc + r * r, 0) / signals.length;
+                const downsideDeviation = Math.sqrt(downsideVariance);
+                // Same epsilon guard as Sharpe — protects against float-artifact downsideDev.
+                if (downsideDeviation > STDDEV_EPSILON) {
+                    sortinoRatio = avgPnl / downsideDeviation;
+                }
+            }
         }
+        // Expected yearly returns via geometric mean of equity curve.
+        // equityFinal^(tradesPerYear / N) - 1 — accounts for volatility drag.
+        // Gated by sample size and calendar span; if account blown → full loss.
+        let expectedYearlyReturns = null;
+        let tradesPerYear = null;
+        if (signals.length >= MIN_SIGNALS_FOR_ANNUALIZATION) {
+            let firstPendingAt = Infinity;
+            let lastCloseAt = -Infinity;
+            for (const s of signals) {
+                if (s.signal.pendingAt < firstPendingAt)
+                    firstPendingAt = s.signal.pendingAt;
+                if (s.closeTimestamp > lastCloseAt)
+                    lastCloseAt = s.closeTimestamp;
+            }
+            const calendarSpanDays = (lastCloseAt - firstPendingAt) / (1000 * 60 * 60 * 24);
+            if (calendarSpanDays >= MIN_CALENDAR_SPAN_DAYS) {
+                // tradesPerYear uses RAW observed frequency — no clipping. If the raw value
+                // exceeds MAX_TRADES_PER_YEAR the sample is too clustered for reliable
+                // annualization, and we leave the annualized metric null instead of silently
+                // understating it with a clipped frequency.
+                const rawTradesPerYear = (signals.length / calendarSpanDays) * 365;
+                if (rawTradesPerYear <= MAX_TRADES_PER_YEAR) {
+                    tradesPerYear = rawTradesPerYear;
+                    if (blown) {
+                        expectedYearlyReturns = -100;
+                    }
+                    else {
+                        // If raw value exceeds MAX_EXPECTED_YEARLY_RETURNS, leave null rather than
+                        // show the cap — capped numbers mislead users into trusting them.
+                        const raw = (Math.pow(equityFinal, tradesPerYear / signals.length) - 1) * 100;
+                        expectedYearlyReturns = Math.abs(raw) > MAX_EXPECTED_YEARLY_RETURNS ? null : raw;
+                    }
+                }
+            }
+        }
+        // Calmar = annualized return / equity-curve max drawdown, capped at ±MAX_CALMAR_RATIO.
+        // Recovery Factor uses the compounded total return (equityFinal-1)*100, not arithmetic
+        // totalPnl — denominator is compounded so numerator must match. Null when account blown.
         let calmarRatio = null;
         let recoveryFactor = null;
-        if (maxAbsFall > 0 && totalPnl !== null) {
-            calmarRatio = expectedYearlyReturns / maxAbsFall;
-            recoveryFactor = totalPnl / maxAbsFall;
+        if (maxDrawdown !== null && maxDrawdown > 0) {
+            if (expectedYearlyReturns !== null) {
+                const raw = expectedYearlyReturns / maxDrawdown;
+                calmarRatio = Math.max(-MAX_CALMAR_RATIO, Math.min(MAX_CALMAR_RATIO, raw));
+            }
+            if (!blown && canComputeRatios) {
+                // Gated below MIN_SIGNALS_FOR_RATIOS like Sharpe — a Recovery Factor on
+                // a handful of trades is statistically meaningless, so don't surface it
+                // per-symbol while Sharpe is N/A.
+                // Same MAX_CALMAR_RATIO clamp as Calmar — both compounded-profit/DD ratios.
+                const rawRec = ((equityFinal - 1) * 100) / maxDrawdown;
+                recoveryFactor = Math.max(-MAX_CALMAR_RATIO, Math.min(MAX_CALMAR_RATIO, rawRec));
+            }
         }
         // Apply safe math checks
         if (isUnsafe(winRate))
@@ -26636,12 +27065,18 @@ class HeatmapStorage {
      * 2. Sorts symbols by `sharpeRatio` descending — best performers first,
      *    symbols with `null` sharpeRatio placed at the end.
      * 3. Computes portfolio-wide aggregates:
-     *    - `portfolioTotalPnl` — sum of all per-symbol `totalPnl` values (treats `null` as 0)
-     *    - `portfolioTotalTrades` — sum of all per-symbol `totalTrades`
-     *    - `portfolioSharpeRatio` — trade-count-weighted average of per-symbol sharpe ratios
-     *
-     * @returns Promise resolving to `HeatmapStatisticsModel` with per-symbol rows and
-     *   portfolio-wide `portfolioTotalPnl`, `portfolioSharpeRatio`, `portfolioTotalTrades`
+     *    - `portfolioTotalPnl` — sum of per-symbol `totalPnl` values, skipping `null` entries
+     *      (so a symbol with no data does not silently contribute 0). If every symbol's
+     *      `totalPnl` is null, the portfolio value is null.
+     *    - `portfolioTotalTrades` — sum of per-symbol `totalTrades`
+     *    - `portfolioSharpeRatio` — POOLED Sharpe over all trades across symbols (sample
+     *      stddev, N-1). NOT a Markowitz portfolio Sharpe — ignores cross-symbol
+     *      correlations and capital allocation. Rendered as "Pooled Sharpe" in the report.
+     *      Gated by `MIN_SIGNALS_FOR_RATIOS` on the pooled count.
+     *    - `portfolioAvgPeakPnl` / `portfolioAvgFallPnl` — trade-count-weighted means
+     *      over symbols that have non-null values.
+     *
+     * @returns Promise resolving to `HeatmapStatisticsModel`
      */
     async getData() {
         const symbols = [];
@@ -26660,31 +27095,53 @@ class HeatmapStorage {
                 return -1;
             return b.sharpeRatio - a.sharpeRatio;
         });
-        // Calculate portfolio-wide metrics
+        // Portfolio totals — sum only over symbols with non-null totalPnl. `s.totalPnl || 0`
+        // would silently treat a missing value as zero and hide that some symbols had no data.
         const totalSymbols = symbols.length;
         let portfolioTotalPnl = null;
         let portfolioTotalTrades = 0;
         if (symbols.length > 0) {
-            portfolioTotalPnl = symbols.reduce((acc, s) => acc + (s.totalPnl || 0), 0);
+            const validTotalPnls = symbols.filter((s) => s.totalPnl !== null);
+            portfolioTotalPnl = validTotalPnls.length > 0
+                ? validTotalPnls.reduce((acc, s) => acc + s.totalPnl, 0)
+                : null;
             portfolioTotalTrades = symbols.reduce((acc, s) => acc + s.totalTrades, 0);
         }
-        // Calculate portfolio Sharpe Ratio (weighted by number of trades)
+        // 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.
         let portfolioSharpeRatio = null;
-        const validSharpes = symbols.filter((s) => s.sharpeRatio !== null);
-        if (validSharpes.length > 0 && portfolioTotalTrades > 0) {
-            const weightedSum = validSharpes.reduce((acc, s) => acc + s.sharpeRatio * s.totalTrades, 0);
-            portfolioSharpeRatio = weightedSum / portfolioTotalTrades;
+        const allReturns = [];
+        for (const signals of this.symbolData.values()) {
+            for (const s of signals) {
+                allReturns.push(s.pnl.pnlPercentage);
+            }
+        }
+        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) /
+                (allReturns.length - 1);
+            const portfolioStdDev = Math.sqrt(portfolioVariance);
+            // STDDEV_EPSILON guard — same protection as per-symbol Sharpe.
+            if (portfolioStdDev > STDDEV_EPSILON) {
+                portfolioSharpeRatio = portfolioAvg / portfolioStdDev;
+            }
         }
-        // Calculate portfolio-wide weighted average peak/fall PNL
+        // Portfolio-wide weighted average peak/fall PNL. Denominator must include only
+        // symbols that contributed a value — otherwise trade-count-weighted mean is diluted
+        // by symbols without the metric.
         let portfolioAvgPeakPnl = null;
         let portfolioAvgFallPnl = null;
         const validPeak = symbols.filter((s) => s.avgPeakPnl !== null);
         const validFall = symbols.filter((s) => s.avgFallPnl !== null);
-        if (validPeak.length > 0 && portfolioTotalTrades > 0) {
-            portfolioAvgPeakPnl = validPeak.reduce((acc, s) => acc + s.avgPeakPnl * s.totalTrades, 0) / portfolioTotalTrades;
+        const peakTradesTotal = validPeak.reduce((acc, s) => acc + s.totalTrades, 0);
+        const fallTradesTotal = validFall.reduce((acc, s) => acc + s.totalTrades, 0);
+        if (validPeak.length > 0 && peakTradesTotal > 0) {
+            portfolioAvgPeakPnl = validPeak.reduce((acc, s) => acc + s.avgPeakPnl * s.totalTrades, 0) / peakTradesTotal;
         }
-        if (validFall.length > 0 && portfolioTotalTrades > 0) {
-            portfolioAvgFallPnl = validFall.reduce((acc, s) => acc + s.avgFallPnl * s.totalTrades, 0) / portfolioTotalTrades;
+        if (validFall.length > 0 && fallTradesTotal > 0) {
+            portfolioAvgFallPnl = validFall.reduce((acc, s) => acc + s.avgFallPnl * s.totalTrades, 0) / fallTradesTotal;
         }
         // Apply safe math
         if (isUnsafe(portfolioTotalPnl))
@@ -26712,7 +27169,7 @@ class HeatmapStorage {
      * ```
      * # Portfolio Heatmap: {strategyName}
      *
-     * **Total Symbols:** N | **Portfolio PNL:** X% | **Portfolio Sharpe:** Y | **Total Trades:** Z
+     * **Total Symbols:** N | **Portfolio PNL:** X% | **Pooled Sharpe:** Y | **Total Trades:** Z
      *
      * | col1 | col2 | ... |
      * | ---  | ---  | ... |
@@ -26751,18 +27208,21 @@ class HeatmapStorage {
         return [
             `# Portfolio Heatmap: ${strategyName}`,
             "",
-            `**Total Symbols:** ${data.totalSymbols} | **Portfolio PNL:** ${data.portfolioTotalPnl !== null ? str(data.portfolioTotalPnl, "%") : "N/A"} | **Portfolio 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"}`,
+            `**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"}`,
             "",
             table,
             "",
             `*Win Rate: reliable above 200+ signals; below 30 signals a single streak can shift it by 10-20%.*`,
+            `*Pooled Sharpe: Sharpe computed over all trades across symbols treated as one sample. NOT a Markowitz portfolio Sharpe — ignores cross-symbol correlations and capital allocation. N/A unless ≥${MIN_SIGNALS_FOR_RATIOS} pooled trades.*`,
             `*Sharpe Ratio: below 1.0 is poor, 1.0-2.0 is acceptable, above 2.0 is strong. Requires 30+ signals per symbol.*`,
-            `*Sortino Ratio: below 1.0 is poor, 1.0-2.0 is acceptable, above 2.0 is strong. Requires 30+ signals.*`,
+            `*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. Based on theoretical yearly returns.*`,
-            `*Recovery Factor: below 1.0 means total profit does not cover max drawdown. Above 3.0 is considered good.*`,
-            `*All metrics require 100+ signals per symbol to be statistically reliable. Time period matters only for Calmar Ratio — it assumes current market conditions hold year-round, which may not reflect reality.*`,
+            `*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.*`,
+            `*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.*`,
+            `*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");
     }
     /**
@@ -26957,7 +27417,7 @@ class HeatMarkdownService {
          * console.log(markdown);
          * // # Portfolio Heatmap: my-strategy
          * //
-         * // **Total Symbols:** 5 | **Portfolio PNL:** +45.3% | **Portfolio Sharpe:** 1.85 | **Total Trades:** 120
+         * // **Total Symbols:** 5 | **Portfolio PNL:** +45.3% | **Pooled Sharpe:** 1.85 | **Total Trades:** 120
          * //
          * // | Symbol | Total PNL | Sharpe | Max DD | Trades |
          * // | ---    | ---       | ---    | ---    | ---    |
@@ -37109,8 +37569,9 @@ function getActionSchema(actionName) {
 }
 
 const WAIT_FOR_READY_METHOD_NAME = "init.waitForReady";
-const MAX_WAIT_SECONDS = 10;
+const MAX_WAIT_SECONDS = 45;
 const SECOND_DELAY = 1000;
+const TIMEOUT_SYMBOL = Symbol('timeout');
 /**
  * Blocks until the schema registries needed to start trading are populated.
  *
@@ -37148,6 +37609,18 @@ const SECOND_DELAY = 1000;
  */
 async function waitForReady(isBacktest = true) {
     backtest.loggerService.info(WAIT_FOR_READY_METHOD_NAME, { isBacktest });
+    if (entrySubject.data) {
+        return;
+    }
+    if (entrySubject.hasListeners) {
+        backtest.loggerService.debug(`${WAIT_FOR_READY_METHOD_NAME} waiting for entrySubject`);
+        const result = await Promise.race([
+            entrySubject.toPromise(),
+            sleep(MAX_WAIT_SECONDS * SECOND_DELAY).then(() => TIMEOUT_SYMBOL)
+        ]);
+        typeof result === "symbol" && console.log("waitForReady timeout");
+        return;
+    }
     for (let i = 0; i !== MAX_WAIT_SECONDS; i++) {
         const [exchangeList, frameList, strategyList] = await Promise.all([
             backtest.exchangeValidationService.list(),
@@ -37178,6 +37651,9 @@ async function waitForReady(isBacktest = true) {
             await sleep(SECOND_DELAY);
             continue;
         }
+        if (i === MAX_WAIT_SECONDS - 1) {
+            console.log("waitForReady timeout");
+        }
         break;
     }
 }
@@ -54969,7 +55445,7 @@ class LogJsonlUtils {
             await this[WAIT_FOR_INIT_SYMBOL]();
             const line = JSON.stringify(entry) + "\n";
             const status = await this[WRITE_SAFE_SYMBOL](line);
-            if (status === TIMEOUT_SYMBOL$1) {
+            if (status === TIMEOUT_SYMBOL$2) {
                 throw new Error(`LogJsonlUtils timeout writing to file=${this._filePath}`);
             }
         };
@@ -63263,6 +63739,7 @@ const CRON_METHOD_NAME_CLEAR = "CronUtils.clear";
 const CRON_METHOD_NAME_TICK = "CronUtils._tick";
 const CRON_METHOD_NAME_ENABLE = "CronUtils.enable";
 const CRON_METHOD_NAME_DISABLE = "CronUtils.disable";
+const CRON_METHOD_NAME_DISPOSE = "CronUtils.dispose";
 /**
  * Local logger instance.
  *
@@ -63652,6 +64129,38 @@ class CronUtils {
                 lastSubscription();
             }
         };
+        /**
+         * Hard-reset the entire `Cron` state.
+         *
+         * Performs in order:
+         * 1. {@link disable} — tears down lifecycle subscriptions and resets the
+         *    `enable` singleshot so a future `enable()` re-subscribes cleanly.
+         * 2. Wipes `_entries` — every {@link register}'ed entry is forgotten.
+         *    Disposers returned by previous `register()` calls become no-ops
+         *    (their `unregister(name)` will not find anything to remove).
+         * 3. Wipes `_firedOnce` — all fire-once marks are dropped, so any future
+         *    re-registration of the same `name` fires again on the next matching
+         *    tick.
+         * 4. Does **not** touch `_inFlight` — in-flight handlers continue to
+         *    settle in the background and clear their own slots via `.finally()`.
+         *    Their final `_firedOnce.add(firedKey)` writes carry old-generation
+         *    keys and are harmless (lookup uses the post-dispose generation).
+         *
+         * Use from a CLI/session teardown when you want to throw away every
+         * registration along with the lifecycle wiring — e.g. between two
+         * independent runner scopes. For "just snap the subscriptions but keep
+         * registrations" use {@link disable} instead; for "just re-arm fire-once
+         * marks" use {@link clear}.
+         *
+         * Idempotent. Safe to call multiple times and safe to call before
+         * `enable()` / without any registrations.
+         */
+        this.dispose = () => {
+            LOGGER_SERVICE$1.info(CRON_METHOD_NAME_DISPOSE);
+            this.disable();
+            this._entries.clear();
+            this._firedOnce.clear();
+        };
     }
     /**
      * Garbage-collect every `_firedOnce` key that belongs to the entry `name`