tradelab 1.1.0 → 1.2.1

package/docs/superpowers/plans/2026-01-metrics-correctness.md

@@ -1,873 +0,0 @@
-# Metrics Correctness Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Make `buildMetrics` output safe to serialize and comparable across timeframes — annualize the risk ratios, clamp non-finite values, and add benchmark-relative alpha/beta/information-ratio.
-
-**Architecture:** Three small pure helpers (`finite.js`, `annualize.js`, `benchmark.js`) feed into the existing `buildMetrics`. `buildMetrics` gains two optional inputs (`interval`, `benchmarkReturns`) and emits new keys only — no existing key is renamed or removed. Every engine that calls `buildMetrics` (`backtest`, `backtestTicks`, `barSystemRunner`, `walkForward`, `portfolio`) passes the `interval` it already knows.
-
-**Tech Stack:** Node ESM, `node:test`.
-
----
-
-### Task 1: Finite-clamping helper
-
-**Files:**
-
-- Create: `src/metrics/finite.js`
-- Test: `test/metrics/finite.test.js`
-
-- [ ] **Step 1: Write the failing test**
-
-```js
-// test/metrics/finite.test.js
-import test from "node:test";
-import assert from "node:assert/strict";
-import { clampFinite, BIG_NUMBER } from "../../src/metrics/finite.js";
-
-test("clampFinite passes finite numbers through", () => {
-  assert.equal(clampFinite(1.5), 1.5);
-  assert.equal(clampFinite(0), 0);
-  assert.equal(clampFinite(-3), -3);
-});
-
-test("clampFinite maps +Infinity to +BIG_NUMBER and -Infinity to -BIG_NUMBER", () => {
-  assert.equal(clampFinite(Infinity), BIG_NUMBER);
-  assert.equal(clampFinite(-Infinity), -BIG_NUMBER);
-});
-
-test("clampFinite maps NaN/undefined/null to the fallback (default 0)", () => {
-  assert.equal(clampFinite(NaN), 0);
-  assert.equal(clampFinite(undefined), 0);
-  assert.equal(clampFinite(null), 0);
-  assert.equal(clampFinite(NaN, -1), -1);
-});
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `node --test test/metrics/finite.test.js`
-Expected: FAIL — cannot find module `../../src/metrics/finite.js`.
-
-- [ ] **Step 3: Write minimal implementation**
-
-```js
-// src/metrics/finite.js
-
-// Sentinel for "effectively infinite" metric values (e.g. profit factor with zero
-// losses). Large enough to be unmistakable, small enough to survive JSON.stringify
-// and JSON.parse round-trips without becoming Infinity.
-export const BIG_NUMBER = 1e9;
-
-/**
- * Coerce a metric to a finite, JSON-safe number.
- * +/-Infinity clamp to +/-BIG_NUMBER. NaN/null/undefined become `fallback`.
- */
-export function clampFinite(value, fallback = 0) {
-  if (value === Infinity) return BIG_NUMBER;
-  if (value === -Infinity) return -BIG_NUMBER;
-  if (typeof value === "number" && Number.isFinite(value)) return value;
-  return fallback;
-}
-```
-
-- [ ] **Step 4: Run test to verify it passes**
-
-Run: `node --test test/metrics/finite.test.js`
-Expected: PASS (3 tests).
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add src/metrics/finite.js test/metrics/finite.test.js
-git commit -m "feat: add clampFinite metric helper
-
-Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
-```
-
----
-
-### Task 2: Annualization factor from interval
-
-**Files:**
-
-- Create: `src/metrics/annualize.js`
-- Test: `test/metrics/annualize.test.js`
-
-- [ ] **Step 1: Write the failing test**
-
-```js
-// test/metrics/annualize.test.js
-import test from "node:test";
-import assert from "node:assert/strict";
-import { periodsPerYear } from "../../src/metrics/annualize.js";
-
-test("periodsPerYear maps common intervals to trading-period counts", () => {
-  assert.equal(periodsPerYear("1d"), 252);
-  assert.equal(periodsPerYear("1h"), 252 * 6.5);
-  assert.equal(periodsPerYear("5m"), 252 * 6.5 * 12);
-  assert.equal(periodsPerYear("1wk"), 52);
-});
-
-test("periodsPerYear falls back to estBarMs when interval is unknown", () => {
-  // 1-hour bars in ms, 24/7 market assumption => 24*365 periods
-  const oneHourMs = 60 * 60 * 1000;
-  assert.equal(
-    periodsPerYear("weird", oneHourMs),
-    Math.round((365 * 24 * 60 * 60 * 1000) / oneHourMs)
-  );
-});
-
-test("periodsPerYear returns 252 when nothing is resolvable", () => {
-  assert.equal(periodsPerYear(undefined, undefined), 252);
-});
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `node --test test/metrics/annualize.test.js`
-Expected: FAIL — cannot find module.
-
-- [ ] **Step 3: Write minimal implementation**
-
-```js
-// src/metrics/annualize.js
-
-const TRADING_DAYS = 252;
-const RTH_HOURS = 6.5; // US regular trading hours per day
-const MS_PER_YEAR = 365 * 24 * 60 * 60 * 1000;
-
-// Known intra/inter-day intervals => periods per trading year.
-const INTERVAL_PERIODS = {
-  "1m": TRADING_DAYS * RTH_HOURS * 60,
-  "2m": TRADING_DAYS * RTH_HOURS * 30,
-  "5m": TRADING_DAYS * RTH_HOURS * 12,
-  "15m": TRADING_DAYS * RTH_HOURS * 4,
-  "30m": TRADING_DAYS * RTH_HOURS * 2,
-  "1h": TRADING_DAYS * RTH_HOURS,
-  "60m": TRADING_DAYS * RTH_HOURS,
-  "1d": TRADING_DAYS,
-  "1wk": 52,
-  "1mo": 12,
-};
-
-/**
- * Number of bars in one year for the given interval. Used to annualize
- * per-bar Sharpe/Sortino. Falls back to estBarMs (assuming a 24/7 clock)
- * when the interval string is unknown, then to 252.
- */
-export function periodsPerYear(interval, estBarMs) {
-  if (interval && INTERVAL_PERIODS[interval]) return INTERVAL_PERIODS[interval];
-  if (Number.isFinite(estBarMs) && estBarMs > 0) {
-    return Math.round(MS_PER_YEAR / estBarMs);
-  }
-  return TRADING_DAYS;
-}
-```
-
-- [ ] **Step 4: Run test to verify it passes**
-
-Run: `node --test test/metrics/annualize.test.js`
-Expected: PASS (3 tests).
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add src/metrics/annualize.js test/metrics/annualize.test.js
-git commit -m "feat: add periodsPerYear annualization helper
-
-Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
-```
-
----
-
-### Task 3: Benchmark-relative metrics (alpha/beta/IR/correlation)
-
-**Files:**
-
-- Create: `src/metrics/benchmark.js`
-- Test: `test/metrics/benchmark.test.js`
-
-- [ ] **Step 1: Write the failing test**
-
-```js
-// test/metrics/benchmark.test.js
-import test from "node:test";
-import assert from "node:assert/strict";
-import { benchmarkStats } from "../../src/metrics/benchmark.js";
-
-test("perfectly correlated 2x strategy has beta 2 and ~zero alpha", () => {
-  const bench = [0.01, -0.02, 0.03, -0.01, 0.02];
-  const strat = bench.map((r) => r * 2);
-  const stats = benchmarkStats(strat, bench);
-  assert.ok(Math.abs(stats.beta - 2) < 1e-9);
-  assert.ok(Math.abs(stats.alpha) < 1e-9);
-  assert.ok(Math.abs(stats.correlation - 1) < 1e-9);
-});
-
-test("mismatched lengths return null stats", () => {
-  assert.equal(benchmarkStats([0.01], [0.01, 0.02]).beta, null);
-});
-
-test("empty inputs return null stats", () => {
-  assert.equal(benchmarkStats([], []).beta, null);
-});
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `node --test test/metrics/benchmark.test.js`
-Expected: FAIL — cannot find module.
-
-- [ ] **Step 3: Write minimal implementation**
-
-```js
-// src/metrics/benchmark.js
-
-function mean(xs) {
-  return xs.length ? xs.reduce((a, b) => a + b, 0) / xs.length : 0;
-}
-
-/**
- * Ordinary least squares of strategy returns on benchmark returns.
- * Returns { alpha, beta, correlation, informationRatio, trackingError }.
- * `alpha` is per-period excess return (intercept). All null when inputs are
- * empty or length-mismatched.
- */
-export function benchmarkStats(strategyReturns, benchmarkReturns) {
-  const nullStats = {
-    alpha: null,
-    beta: null,
-    correlation: null,
-    informationRatio: null,
-    trackingError: null,
-  };
-  if (
-    !Array.isArray(strategyReturns) ||
-    !Array.isArray(benchmarkReturns) ||
-    strategyReturns.length === 0 ||
-    strategyReturns.length !== benchmarkReturns.length
-  ) {
-    return nullStats;
-  }
-
-  const meanStrat = mean(strategyReturns);
-  const meanBench = mean(benchmarkReturns);
-
-  let covar = 0;
-  let varBench = 0;
-  let varStrat = 0;
-  for (let i = 0; i < strategyReturns.length; i += 1) {
-    const ds = strategyReturns[i] - meanStrat;
-    const db = benchmarkReturns[i] - meanBench;
-    covar += ds * db;
-    varBench += db * db;
-    varStrat += ds * ds;
-  }
-
-  const beta = varBench === 0 ? 0 : covar / varBench;
-  const alpha = meanStrat - beta * meanBench;
-  const denom = Math.sqrt(varStrat * varBench);
-  const correlation = denom === 0 ? 0 : covar / denom;
-
-  const active = strategyReturns.map((r, i) => r - benchmarkReturns[i]);
-  const meanActive = mean(active);
-  const trackingError = Math.sqrt(mean(active.map((a) => (a - meanActive) ** 2)));
-  const informationRatio = trackingError === 0 ? 0 : meanActive / trackingError;
-
-  return { alpha, beta, correlation, informationRatio, trackingError };
-}
-```
-
-- [ ] **Step 4: Run test to verify it passes**
-
-Run: `node --test test/metrics/benchmark.test.js`
-Expected: PASS (3 tests).
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add src/metrics/benchmark.js test/metrics/benchmark.test.js
-git commit -m "feat: add benchmarkStats alpha/beta/IR helper
-
-Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
-```
-
----
-
-### Task 4: Wire annualization + clamping + benchmark into buildMetrics
-
-**Files:**
-
-- Modify: `src/metrics/buildMetrics.js`
-- Test: `test/metrics/buildMetrics.test.js` (new)
-
-`buildMetrics` currently has signature
-`buildMetrics({ closed, equityStart, equityFinal, candles, estBarMs, eqSeries })`.
-Add two optional fields: `interval` and `benchmarkReturns`.
-
-- [ ] **Step 1: Write the failing test**
-
-```js
-// test/metrics/buildMetrics.test.js
-import test from "node:test";
-import assert from "node:assert/strict";
-import { buildMetrics } from "../../src/metrics/buildMetrics.js";
-import { BIG_NUMBER } from "../../src/metrics/finite.js";
-
-function leg({ time, pnl, side = "long" }) {
-  return {
-    side,
-    entry: 100,
-    entryFill: 100,
-    _initRisk: 1,
-    openTime: time - 60_000,
-    exit: { price: 100 + pnl, time, reason: pnl >= 0 ? "TP" : "SL", pnl },
-  };
-}
-
-test("profitFactor with zero losses is clamped to BIG_NUMBER, not Infinity", () => {
-  const closed = [leg({ time: 2_000, pnl: 5 }), leg({ time: 3_000, pnl: 7 })];
-  const m = buildMetrics({
-    closed,
-    equityStart: 1000,
-    equityFinal: 1012,
-    candles: [
-      { time: 1_000, close: 100 },
-      { time: 2_000, close: 100 },
-    ],
-    estBarMs: 1000,
-    eqSeries: [],
-    interval: "1d",
-  });
-  assert.equal(Number.isFinite(m.profitFactor), true);
-  assert.equal(m.profitFactor, BIG_NUMBER);
-  // every numeric field survives a JSON round-trip with no Infinity/NaN
-  const round = JSON.parse(JSON.stringify(m));
-  for (const v of Object.values(round)) {
-    if (typeof v === "number") assert.equal(Number.isFinite(v), true);
-  }
-});
-
-test("sharpeAnnualized scales the per-period daily sharpe by sqrt(periodsPerYear)", () => {
-  const closed = [
-    leg({ time: 2 * 86_400_000, pnl: 5 }),
-    leg({ time: 3 * 86_400_000, pnl: -3 }),
-    leg({ time: 4 * 86_400_000, pnl: 6 }),
-  ];
-  const m = buildMetrics({
-    closed,
-    equityStart: 1000,
-    equityFinal: 1008,
-    candles: [{ time: 0, close: 100 }],
-    estBarMs: 86_400_000,
-    eqSeries: [],
-    interval: "1d",
-  });
-  assert.equal("sharpeAnnualized" in m, true);
-  if (Number.isFinite(m.sharpe) && m.sharpe !== 0) {
-    assert.ok(Math.abs(m.sharpeAnnualized - m.sharpe * Math.sqrt(252)) < 1e-6);
-  }
-});
-
-test("benchmarkReturns produce a benchmark block with beta", () => {
-  const closed = [leg({ time: 2_000, pnl: 5 }), leg({ time: 3_000, pnl: -2 })];
-  const m = buildMetrics({
-    closed,
-    equityStart: 1000,
-    equityFinal: 1003,
-    candles: [{ time: 1_000, close: 100 }],
-    estBarMs: 1000,
-    eqSeries: [],
-    interval: "1d",
-    benchmarkReturns: [0.01, -0.005],
-  });
-  assert.equal(typeof m.benchmark, "object");
-  assert.equal("beta" in m.benchmark, true);
-});
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `node --test test/metrics/buildMetrics.test.js`
-Expected: FAIL — `sharpeAnnualized`/`benchmark` undefined, `profitFactor` may be a finite cap already (`PROFIT_FACTOR_CAP = 1e6`) but `sortino`/`calmar` can still be `Infinity`.
-
-- [ ] **Step 3: Edit buildMetrics.js — imports**
-
-Add at the top of `src/metrics/buildMetrics.js`, after the existing function
-declarations block (the file has no imports today; add these as the first lines):
-
-```js
-import { clampFinite, BIG_NUMBER } from "./finite.js";
-import { periodsPerYear } from "./annualize.js";
-import { benchmarkStats } from "./benchmark.js";
-```
-
-- [ ] **Step 4: Edit buildMetrics.js — replace PROFIT_FACTOR_CAP with BIG_NUMBER**
-
-Find:
-
-```js
-const PROFIT_FACTOR_CAP = 1_000_000;
-
-function finiteProfitFactor(grossProfit, grossLoss) {
-  if (grossLoss === 0) {
-    return grossProfit > 0 ? PROFIT_FACTOR_CAP : 0;
-  }
-  return grossProfit / grossLoss;
-}
-```
-
-Replace with:
-
-```js
-function finiteProfitFactor(grossProfit, grossLoss) {
-  if (grossLoss === 0) {
-    return grossProfit > 0 ? BIG_NUMBER : 0;
-  }
-  return grossProfit / grossLoss;
-}
-```
-
-- [ ] **Step 5: Edit buildMetrics.js — accept interval + benchmarkReturns**
-
-Find the function signature:
-
-```js
-export function buildMetrics({ closed, equityStart, equityFinal, candles, estBarMs, eqSeries }) {
-```
-
-Replace with:
-
-```js
-export function buildMetrics({
-  closed,
-  equityStart,
-  equityFinal,
-  candles,
-  estBarMs,
-  eqSeries,
-  interval,
-  benchmarkReturns,
-}) {
-```
-
-- [ ] **Step 6: Edit buildMetrics.js — compute annualized ratios + benchmark before the return**
-
-Find the line that begins the return object:
-
-```js
-  return {
-    trades: completedTrades.length,
-```
-
-Insert immediately ABOVE that `return {`:
-
-```js
-const periods = periodsPerYear(interval, estBarMs);
-const sqrtPeriods = Math.sqrt(periods);
-const sharpeAnnualized = clampFinite(sharpeDaily) * sqrtPeriods;
-const sortinoAnnualized = clampFinite(sortinoDaily) * sqrtPeriods;
-const benchmark = benchmarkStats(dailyReturnsSeries, benchmarkReturns ?? []);
-```
-
-- [ ] **Step 7: Edit buildMetrics.js — clamp the returned numbers + add new keys**
-
-In the returned object, replace these specific lines:
-
-```js
-    profitFactor: profitFactorPositions,
-```
-
-with
-
-```js
-    profitFactor: clampFinite(profitFactorPositions),
-```
-
-Replace:
-
-```js
-    sharpe: sharpeDaily,
-    sharpePerTrade,
-    sortinoPerTrade,
-```
-
-with
-
-```js
-    sharpe: clampFinite(sharpeDaily),
-    sharpeAnnualized,
-    sortinoAnnualized,
-    sharpePerTrade: clampFinite(sharpePerTrade),
-    sortinoPerTrade: clampFinite(sortinoPerTrade),
-    annualizationPeriods: periods,
-```
-
-Replace:
-
-```js
-    calmar,
-```
-
-with
-
-```js
-    calmar: clampFinite(calmar),
-```
-
-Replace:
-
-```js
-    sharpeDaily,
-    sortinoDaily,
-```
-
-with
-
-```js
-    sharpeDaily: clampFinite(sharpeDaily),
-    sortinoDaily: clampFinite(sortinoDaily),
-    benchmark,
-```
-
-- [ ] **Step 8: Run the new test + full suite**
-
-Run: `node --test test/metrics/buildMetrics.test.js`
-Expected: PASS (3 tests).
-
-Run: `node --test`
-Expected: PASS — existing `backtest.test.js`, `reporting.test.js` still green
-(new keys are additive; `sharpe` is still present and now finite).
-
-- [ ] **Step 9: Commit**
-
-```bash
-git add src/metrics/buildMetrics.js test/metrics/buildMetrics.test.js
-git commit -m "feat: annualize + clamp metrics and add benchmark block
-
-Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
-```
-
----
-
-### Task 5: Pass `interval` through every engine call site
-
-`buildMetrics` now reads `interval`. Each engine already knows its interval; thread it in.
-
-**Files:**
-
-- Modify: `src/engine/backtest.js` (the `buildMetrics({...})` call near the end)
-- Modify: `src/engine/barSystemRunner.js` (`buildResult()` → `buildMetrics({...})`)
-- Modify: `src/engine/backtestTicks.js` (the `buildMetrics({...})` call)
-- Modify: `src/engine/walkForward.js` (the final `buildMetrics({...})` call)
-- Test: reuse `test/backtest.test.js` (assert annualized field is present)
-
-- [ ] **Step 1: Write the failing test (append to test/backtest.test.js)**
-
-```js
-test("backtest result metrics expose sharpeAnnualized", () => {
-  const candles = buildCandles();
-  const result = backtest({
-    candles,
-    interval: "5m",
-    warmupBars: 1,
-    flattenAtClose: false,
-    signal({ index, bar }) {
-      if (index !== 1) return null;
-      return { side: "buy", stop: bar.close - 1, rr: 2 };
-    },
-  });
-  assert.equal("sharpeAnnualized" in result.metrics, true);
-  assert.equal(result.metrics.annualizationPeriods > 0, true);
-});
-```
-
-- [ ] **Step 2: Run to verify it fails**
-
-Run: `node --test test/backtest.test.js`
-Expected: PASS already for `"sharpeAnnualized" in metrics` (Task 4 added it) BUT
-`annualizationPeriods` will reflect a wrong fallback because `interval` is not
-passed yet. To make the failure explicit, the assertion `annualizationPeriods > 0`
-passes via estBarMs fallback — so instead verify the interval is honored:
-
-Replace the last assertion with:
-
-```js
-assert.equal(result.metrics.annualizationPeriods, 252 * 6.5 * 12); // 5m
-```
-
-Re-run: `node --test test/backtest.test.js`
-Expected: FAIL — `annualizationPeriods` came from estBarMs fallback, not "5m".
-
-- [ ] **Step 3: Edit backtest.js**
-
-Find:
-
-```js
-const metrics = buildMetrics({
-  closed,
-  equityStart: equity,
-  equityFinal: currentEquity,
-  candles,
-  estBarMs: estimatedBarMs,
-  eqSeries,
-});
-```
-
-Replace with:
-
-```js
-const metrics = buildMetrics({
-  closed,
-  equityStart: equity,
-  equityFinal: currentEquity,
-  candles,
-  estBarMs: estimatedBarMs,
-  eqSeries,
-  interval: options.interval,
-});
-```
-
-- [ ] **Step 4: Edit barSystemRunner.js `buildResult()`**
-
-Find inside `buildResult()`:
-
-```js
-const metrics = buildMetrics({
-  closed: this.closed,
-  equityStart: this.options.equity,
-  equityFinal: this.currentEquity,
-  candles: this.candles,
-  estBarMs: this.estimatedBarMs,
-  eqSeries: this.eqSeries,
-});
-```
-
-Replace with:
-
-```js
-const metrics = buildMetrics({
-  closed: this.closed,
-  equityStart: this.options.equity,
-  equityFinal: this.currentEquity,
-  candles: this.candles,
-  estBarMs: this.estimatedBarMs,
-  eqSeries: this.eqSeries,
-  interval: this.options.interval,
-});
-```
-
-- [ ] **Step 5: Edit backtestTicks.js**
-
-Find:
-
-```js
-const metrics = buildMetrics({
-  closed: trades,
-  equityStart: equity,
-  equityFinal: currentEquity,
-  candles: normalizedTicks,
-  estBarMs:
-    normalizedTicks.length > 1 ? Math.max(1, normalizedTicks[1].time - normalizedTicks[0].time) : 1,
-  eqSeries,
-});
-```
-
-Replace with (add `interval` — the param already exists in the function signature):
-
-```js
-const metrics = buildMetrics({
-  closed: trades,
-  equityStart: equity,
-  equityFinal: currentEquity,
-  candles: normalizedTicks,
-  estBarMs:
-    normalizedTicks.length > 1 ? Math.max(1, normalizedTicks[1].time - normalizedTicks[0].time) : 1,
-  eqSeries,
-  interval,
-});
-```
-
-- [ ] **Step 6: Edit walkForward.js**
-
-Find the final `buildMetrics({...})` call (the one after the windows loop):
-
-```js
-const metrics = buildMetrics({
-  closed: allTrades,
-  equityStart: backtestOptions.equity ?? 10_000,
-  equityFinal: rollingEquity,
-  candles,
-  estBarMs: estimateBarMs(candles),
-  eqSeries,
-});
-```
-
-Replace with:
-
-```js
-const metrics = buildMetrics({
-  closed: allTrades,
-  equityStart: backtestOptions.equity ?? 10_000,
-  equityFinal: rollingEquity,
-  candles,
-  estBarMs: estimateBarMs(candles),
-  eqSeries,
-  interval: backtestOptions.interval,
-});
-```
-
-- [ ] **Step 7: Run the test + full suite**
-
-Run: `node --test test/backtest.test.js`
-Expected: PASS — `annualizationPeriods === 252 * 6.5 * 12`.
-
-Run: `node --test`
-Expected: PASS (all suites).
-
-- [ ] **Step 8: Lint + commit**
-
-```bash
-npm run lint
-git add src/engine/backtest.js src/engine/barSystemRunner.js src/engine/backtestTicks.js src/engine/walkForward.js test/backtest.test.js
-git commit -m "feat: thread interval into buildMetrics across all engines
-
-Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
-```
-
----
-
-### Task 6: Expose benchmark wiring + docs
-
-**Files:**
-
-- Modify: `src/engine/backtest.js` (accept `benchmarkReturns` option, forward it)
-- Modify: `src/index.js` (export `benchmarkStats`)
-- Modify: `docs/backtest-engine.md` (document new metric fields)
-
-- [ ] **Step 1: Write the failing test (append to test/backtest.test.js)**
-
-```js
-test("backtest forwards benchmarkReturns into metrics.benchmark", () => {
-  const candles = buildCandles();
-  const result = backtest({
-    candles,
-    interval: "5m",
-    warmupBars: 1,
-    flattenAtClose: false,
-    benchmarkReturns: Array.from({ length: 40 }, () => 0.001),
-    signal({ index, bar }) {
-      if (index !== 1) return null;
-      return { side: "buy", stop: bar.close - 1, rr: 2 };
-    },
-  });
-  assert.equal(typeof result.metrics.benchmark, "object");
-});
-```
-
-- [ ] **Step 2: Run to verify it fails**
-
-Run: `node --test test/backtest.test.js`
-Expected: FAIL — `benchmarkReturns` is dropped (not in `mergeOptions`), so
-`metrics.benchmark.beta` is null but the block exists from Task 4... it WILL be an
-object already. To force a real failure, assert the data flows:
-
-Change the assertion to:
-
-```js
-assert.equal(result.metrics.benchmark.beta !== null, true);
-```
-
-Re-run: FAIL — `benchmarkReturns` never reaches `buildMetrics`, so beta is null.
-
-- [ ] **Step 3: Edit backtest.js mergeOptions**
-
-In `mergeOptions` (the returned object), add after `collectReplay: ...`:
-
-```js
-    benchmarkReturns: Array.isArray(options.benchmarkReturns) ? options.benchmarkReturns : null,
-```
-
-Then add `benchmarkReturns` to the destructure at the top of `backtest()` (the
-`const { candles, symbol, ... } = options;` block) and pass it into the final
-`buildMetrics({...})` call as `benchmarkReturns`.
-
-Concretely, change the final call to:
-
-```js
-const metrics = buildMetrics({
-  closed,
-  equityStart: equity,
-  equityFinal: currentEquity,
-  candles,
-  estBarMs: estimatedBarMs,
-  eqSeries,
-  interval: options.interval,
-  benchmarkReturns: options.benchmarkReturns,
-});
-```
-
-(Reading from `options.benchmarkReturns` avoids touching the destructure list.)
-
-- [ ] **Step 4: Edit src/index.js — export benchmarkStats**
-
-Add to the metrics export line. Find:
-
-```js
-export { buildMetrics } from "./metrics/buildMetrics.js";
-```
-
-Add below it:
-
-```js
-export { benchmarkStats } from "./metrics/benchmark.js";
-export { clampFinite, BIG_NUMBER } from "./metrics/finite.js";
-export { periodsPerYear } from "./metrics/annualize.js";
-```
-
-- [ ] **Step 5: Run test + full suite**
-
-Run: `node --test test/backtest.test.js`
-Expected: PASS.
-
-Run: `node --test`
-Expected: PASS.
-
-- [ ] **Step 6: Document new fields in docs/backtest-engine.md**
-
-Under the result-shape / metrics section, add a short subsection:
-
-```markdown
-### Risk-adjusted metrics
-
-- `sharpe` / `sortino` are per-period (daily-bucketed).
-- `sharpeAnnualized` / `sortinoAnnualized` scale by `sqrt(annualizationPeriods)`,
-  where `annualizationPeriods` is derived from `interval` (falling back to the
-  median bar spacing). Use these to compare strategies across timeframes.
-- `profitFactor`, `calmar`, and the Sharpe/Sortino family are clamped to a finite
-  `BIG_NUMBER` (1e9) so `metrics` JSON never contains `Infinity` or `NaN`.
-- `benchmark` (`{ alpha, beta, correlation, informationRatio, trackingError }`)
-  is populated when you pass `benchmarkReturns` (per-day return array aligned to
-  the strategy's daily equity buckets) to `backtest()`.
-```
-
-- [ ] **Step 7: Lint, format, commit**
-
-```bash
-npm run lint && npm run format
-git add src/engine/backtest.js src/index.js docs/backtest-engine.md test/backtest.test.js
-git commit -m "feat: expose benchmarkReturns option and finite/annualize exports
-
-Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
-```
-
----
-
-## Self-review checklist
-
-- [ ] `sharpe` field still exists (dashboards depend on it) — only its value is now clamped. ✔ (Task 4 Step 7)
-- [ ] No metric key renamed/removed; only additions (`sharpeAnnualized`, `sortinoAnnualized`, `annualizationPeriods`, `benchmark`). ✔
-- [ ] `BIG_NUMBER` replaces the old `PROFIT_FACTOR_CAP` consistently. ✔
-- [ ] All 5 `buildMetrics` call sites pass `interval`. ✔ (Tasks 5)
-- [ ] JSON round-trip test guarantees no `Infinity`/`NaN` leaks. ✔ (Task 4 Step 1)