tradelab 1.0.1 → 1.1.0

package/docs/superpowers/plans/2026-03-overfitting-toolkit.md

@@ -0,0 +1,882 @@
+# Overfitting & Inference Toolkit 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:** Give tradelab the López de Prado statistical kit — seeded Monte Carlo equity bands, Deflated Sharpe Ratio, Probability of Backtest Overfitting (via CSCV), Combinatorial Purged Cross-Validation splits, and a parameter-sweep haircut — so a result can be defended, not just admired.
+
+**Architecture:** A new `src/research/` namespace, exported at top level from `src/index.js` under a `research` object (e.g. `research.monteCarlo`). Pure functions, no engine coupling — they consume trade PnLs, return series, or a performance matrix. Randomness is seeded through a shared `src/utils/random.js` so every run is reproducible.
+
+**Tech Stack:** Node ESM, `node:test`. No new dependencies. Depends on Plan 1 only for the `clampFinite` convention (not a hard import).
+
+---
+
+### Task 1: Seeded RNG utility
+
+**Files:**
+
+- Create: `src/utils/random.js` (skip if it already exists from Plan 4 — verify content matches before reusing)
+- Test: `test/utils/random.test.js`
+
+- [ ] **Step 1: Write the failing test**
+
+```js
+// test/utils/random.test.js
+import test from "node:test";
+import assert from "node:assert/strict";
+import { makeRng, randInt } from "../../src/utils/random.js";
+
+test("makeRng is deterministic for a given seed", () => {
+  const a = makeRng("abc");
+  const b = makeRng("abc");
+  assert.deepEqual([a(), a(), a()], [b(), b(), b()]);
+});
+
+test("different seeds diverge", () => {
+  const a = makeRng("abc");
+  const b = makeRng("xyz");
+  assert.notEqual(a(), b());
+});
+
+test("rng output is in [0,1) and randInt in [0,max)", () => {
+  const rng = makeRng(7);
+  for (let i = 0; i < 100; i += 1) {
+    const v = rng();
+    assert.ok(v >= 0 && v < 1);
+    const n = randInt(rng, 5);
+    assert.ok(Number.isInteger(n) && n >= 0 && n < 5);
+  }
+});
+```
+
+- [ ] **Step 2: Run to verify it fails**
+
+Run: `node --test test/utils/random.test.js`
+Expected: FAIL — cannot find module (unless Plan 4 already created it, in which case this test should PASS and you skip to Step 4).
+
+- [ ] **Step 3: Implement src/utils/random.js**
+
+```js
+// src/utils/random.js
+
+function xmur3(str) {
+  let h = 1779033703 ^ str.length;
+  for (let i = 0; i < str.length; i += 1) {
+    h = Math.imul(h ^ str.charCodeAt(i), 3432918353);
+    h = (h << 13) | (h >>> 19);
+  }
+  return () => {
+    h = Math.imul(h ^ (h >>> 16), 2246822507);
+    h = Math.imul(h ^ (h >>> 13), 3266489909);
+    return (h ^= h >>> 16) >>> 0;
+  };
+}
+
+function mulberry32(seed) {
+  let state = seed >>> 0;
+  return () => {
+    state = (state + 0x6d2b79f5) >>> 0;
+    let t = Math.imul(state ^ (state >>> 15), state | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+/** Returns a deterministic () => float-in-[0,1) generator seeded by `seed`. */
+export function makeRng(seed = "tradelab") {
+  const seedFn = xmur3(String(seed));
+  return mulberry32(seedFn());
+}
+
+/** Integer in [0, maxExclusive) from an rng produced by makeRng. */
+export function randInt(rng, maxExclusive) {
+  return Math.floor(rng() * maxExclusive);
+}
+```
+
+- [ ] **Step 4: Run to verify it passes**
+
+Run: `node --test test/utils/random.test.js`
+Expected: PASS (3 tests).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/utils/random.js test/utils/random.test.js
+git commit -m "feat: add seeded RNG utility
+
+Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 2: Monte Carlo equity bands (block bootstrap of trade PnLs)
+
+**Files:**
+
+- Create: `src/research/monteCarlo.js`
+- Test: `test/research/monteCarlo.test.js`
+
+- [ ] **Step 1: Write the failing test**
+
+```js
+// test/research/monteCarlo.test.js
+import test from "node:test";
+import assert from "node:assert/strict";
+import { monteCarlo } from "../../src/research/monteCarlo.js";
+
+test("monteCarlo returns ordered percentile bands and is seed-deterministic", () => {
+  const pnls = [10, -5, 8, -3, 12, -7, 6, -2, 9, -4];
+  const a = monteCarlo({ tradePnls: pnls, equityStart: 1000, iterations: 500, seed: 42 });
+  const b = monteCarlo({ tradePnls: pnls, equityStart: 1000, iterations: 500, seed: 42 });
+
+  assert.deepEqual(a.finalEquity, b.finalEquity); // determinism
+  assert.ok(a.finalEquity.p5 <= a.finalEquity.p50);
+  assert.ok(a.finalEquity.p50 <= a.finalEquity.p95);
+  assert.ok(a.maxDrawdown.p95 >= a.maxDrawdown.p50);
+  assert.equal(a.iterations, 500);
+});
+
+test("monteCarlo with block bootstrap preserves autocorrelation length option", () => {
+  const pnls = Array.from({ length: 50 }, (_, i) => (i % 5 === 0 ? -8 : 3));
+  const out = monteCarlo({
+    tradePnls: pnls,
+    equityStart: 1000,
+    iterations: 200,
+    blockSize: 5,
+    seed: 1,
+  });
+  assert.equal(out.blockSize, 5);
+  assert.ok(Number.isFinite(out.finalEquity.p50));
+});
+
+test("monteCarlo throws on empty pnls", () => {
+  assert.throws(() => monteCarlo({ tradePnls: [], equityStart: 1000 }));
+});
+```
+
+- [ ] **Step 2: Run to verify it fails**
+
+Run: `node --test test/research/monteCarlo.test.js`
+Expected: FAIL — cannot find module.
+
+- [ ] **Step 3: Implement src/research/monteCarlo.js**
+
+```js
+// src/research/monteCarlo.js
+import { makeRng, randInt } from "../utils/random.js";
+
+function percentile(sorted, p) {
+  if (!sorted.length) return 0;
+  const idx = Math.min(sorted.length - 1, Math.max(0, Math.floor((sorted.length - 1) * p)));
+  return sorted[idx];
+}
+
+function maxDrawdownOf(equityPath) {
+  let peak = equityPath[0];
+  let maxDd = 0;
+  for (const e of equityPath) {
+    if (e > peak) peak = e;
+    const dd = peak > 0 ? (peak - e) / peak : 0;
+    if (dd > maxDd) maxDd = dd;
+  }
+  return maxDd;
+}
+
+/**
+ * Block-bootstrap the trade PnL sequence `iterations` times to produce a
+ * distribution of final equity and max drawdown. `blockSize > 1` resamples
+ * contiguous blocks to preserve short-run autocorrelation (streaks).
+ *
+ * Returns percentile bands { p5, p25, p50, p75, p95 } for finalEquity and
+ * maxDrawdown, plus pathBands (per-step p5/p50/p95 of the equity curve).
+ */
+export function monteCarlo({
+  tradePnls,
+  equityStart = 10_000,
+  iterations = 1000,
+  blockSize = 1,
+  seed = "tradelab-mc",
+}) {
+  if (!Array.isArray(tradePnls) || tradePnls.length === 0) {
+    throw new Error("monteCarlo() requires a non-empty tradePnls array");
+  }
+  const rng = makeRng(seed);
+  const n = tradePnls.length;
+  const block = Math.max(1, Math.floor(blockSize));
+
+  const finals = [];
+  const drawdowns = [];
+  // pathSamples[step] collects equity at that step across iterations
+  const pathSamples = Array.from({ length: n + 1 }, () => []);
+
+  for (let it = 0; it < iterations; it += 1) {
+    const path = [equityStart];
+    let equity = equityStart;
+    let filled = 0;
+    while (filled < n) {
+      const start = randInt(rng, n);
+      for (let k = 0; k < block && filled < n; k += 1) {
+        equity += tradePnls[(start + k) % n];
+        path.push(equity);
+        filled += 1;
+      }
+    }
+    for (let step = 0; step < path.length; step += 1) {
+      pathSamples[step].push(path[step]);
+    }
+    finals.push(equity);
+    drawdowns.push(maxDrawdownOf(path));
+  }
+
+  const sortedFinals = [...finals].sort((a, b) => a - b);
+  const sortedDd = [...drawdowns].sort((a, b) => a - b);
+  const pathBands = pathSamples.map((samples) => {
+    const s = [...samples].sort((a, b) => a - b);
+    return { p5: percentile(s, 0.05), p50: percentile(s, 0.5), p95: percentile(s, 0.95) };
+  });
+
+  const bands = (sorted) => ({
+    p5: percentile(sorted, 0.05),
+    p25: percentile(sorted, 0.25),
+    p50: percentile(sorted, 0.5),
+    p75: percentile(sorted, 0.75),
+    p95: percentile(sorted, 0.95),
+  });
+
+  return {
+    iterations,
+    blockSize: block,
+    finalEquity: bands(sortedFinals),
+    maxDrawdown: bands(sortedDd),
+    pathBands,
+    probProfit: finals.filter((f) => f > equityStart).length / iterations,
+  };
+}
+```
+
+- [ ] **Step 4: Run to verify it passes**
+
+Run: `node --test test/research/monteCarlo.test.js`
+Expected: PASS (3 tests).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/research/monteCarlo.js test/research/monteCarlo.test.js
+git commit -m "feat: add seeded Monte Carlo equity bands
+
+Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 3: Normal distribution helpers + Deflated Sharpe Ratio
+
+**Files:**
+
+- Create: `src/research/stats.js` (normal CDF/PPF, moments)
+- Create: `src/research/deflatedSharpe.js`
+- Test: `test/research/deflatedSharpe.test.js`
+
+- [ ] **Step 1: Write the failing test**
+
+```js
+// test/research/deflatedSharpe.test.js
+import test from "node:test";
+import assert from "node:assert/strict";
+import { normalCdf, normalPpf } from "../../src/research/stats.js";
+import { deflatedSharpe, sweepHaircut } from "../../src/research/deflatedSharpe.js";
+
+test("normalCdf/normalPpf are consistent inverses", () => {
+  assert.ok(Math.abs(normalCdf(0) - 0.5) < 1e-6);
+  assert.ok(Math.abs(normalCdf(1.96) - 0.975) < 1e-3);
+  assert.ok(Math.abs(normalPpf(0.975) - 1.96) < 1e-2);
+});
+
+test("deflatedSharpe falls as the number of trials grows", () => {
+  const base = {
+    sharpe: 2.0,
+    sampleSize: 250,
+    skew: 0,
+    kurtosis: 3,
+    sharpeStd: 0.5,
+  };
+  const few = deflatedSharpe({ ...base, numTrials: 1 });
+  const many = deflatedSharpe({ ...base, numTrials: 100 });
+  assert.ok(many < few);
+  assert.ok(few >= 0 && few <= 1);
+  assert.ok(many >= 0 && many <= 1);
+});
+
+test("sweepHaircut returns the expected-max-sharpe threshold under the null", () => {
+  const hc = sweepHaircut({ numTrials: 50, sharpeStd: 0.4 });
+  assert.ok(hc.expectedMaxSharpe > 0);
+  assert.ok(
+    hc.expectedMaxSharpe > sweepHaircut({ numTrials: 5, sharpeStd: 0.4 }).expectedMaxSharpe
+  );
+});
+```
+
+- [ ] **Step 2: Run to verify it fails**
+
+Run: `node --test test/research/deflatedSharpe.test.js`
+Expected: FAIL — cannot find modules.
+
+- [ ] **Step 3: Implement src/research/stats.js**
+
+```js
+// src/research/stats.js
+
+/** Standard normal CDF via Abramowitz & Stegun 7.1.26 (error < 1.5e-7). */
+export function normalCdf(x) {
+  const sign = x < 0 ? -1 : 1;
+  const ax = Math.abs(x) / Math.SQRT2;
+  const t = 1 / (1 + 0.3275911 * ax);
+  const y =
+    1 -
+    ((((1.061405429 * t - 1.453152027) * t + 1.421413741) * t - 0.284496736) * t + 0.254829592) *
+      t *
+      Math.exp(-ax * ax);
+  return 0.5 * (1 + sign * y);
+}
+
+/** Inverse standard normal CDF (Acklam's algorithm). */
+export function normalPpf(p) {
+  if (p <= 0) return -Infinity;
+  if (p >= 1) return Infinity;
+  const a = [
+    -3.969683028665376e1, 2.209460984245205e2, -2.759285104469687e2, 1.38357751867269e2,
+    -3.066479806614716e1, 2.506628277459239,
+  ];
+  const b = [
+    -5.447609879822406e1, 1.615858368580409e2, -1.556989798598866e2, 6.680131188771972e1,
+    -1.328068155288572e1,
+  ];
+  const c = [
+    -7.784894002430293e-3, -3.223964580411365e-1, -2.400758277161838, -2.549732539343734,
+    4.374664141464968, 2.938163982698783,
+  ];
+  const d = [7.784695709041462e-3, 3.224671290700398e-1, 2.445134137142996, 3.754408661907416];
+  const plow = 0.02425;
+  const phigh = 1 - plow;
+  let q;
+  let r;
+  if (p < plow) {
+    q = Math.sqrt(-2 * Math.log(p));
+    return (
+      (((((c[0] * q + c[1]) * q + c[2]) * q + c[3]) * q + c[4]) * q + c[5]) /
+      ((((d[0] * q + d[1]) * q + d[2]) * q + d[3]) * q + 1)
+    );
+  }
+  if (p <= phigh) {
+    q = p - 0.5;
+    r = q * q;
+    return (
+      ((((((a[0] * r + a[1]) * r + a[2]) * r + a[3]) * r + a[4]) * r + a[5]) * q) /
+      (((((b[0] * r + b[1]) * r + b[2]) * r + b[3]) * r + b[4]) * r + 1)
+    );
+  }
+  q = Math.sqrt(-2 * Math.log(1 - p));
+  return (
+    -(((((c[0] * q + c[1]) * q + c[2]) * q + c[3]) * q + c[4]) * q + c[5]) /
+    ((((d[0] * q + d[1]) * q + d[2]) * q + d[3]) * q + 1)
+  );
+}
+
+/** Sample skewness and excess-aware kurtosis (Pearson, kurtosis includes the +3). */
+export function moments(values) {
+  const n = values.length;
+  if (n < 2) return { mean: values[0] ?? 0, std: 0, skew: 0, kurtosis: 3 };
+  const mean = values.reduce((a, b) => a + b, 0) / n;
+  let m2 = 0;
+  let m3 = 0;
+  let m4 = 0;
+  for (const v of values) {
+    const d = v - mean;
+    m2 += d * d;
+    m3 += d * d * d;
+    m4 += d * d * d * d;
+  }
+  m2 /= n;
+  m3 /= n;
+  m4 /= n;
+  const std = Math.sqrt(m2);
+  const skew = std === 0 ? 0 : m3 / std ** 3;
+  const kurtosis = m2 === 0 ? 3 : m4 / m2 ** 2;
+  return { mean, std, skew, kurtosis };
+}
+```
+
+- [ ] **Step 4: Implement src/research/deflatedSharpe.js**
+
+```js
+// src/research/deflatedSharpe.js
+import { normalCdf, normalPpf } from "./stats.js";
+
+const EULER_MASCHERONI = 0.5772156649015329;
+
+/**
+ * Expected maximum Sharpe under the null (no skill), given `numTrials`
+ * independent strategy trials whose Sharpe estimates have std `sharpeStd`.
+ * López de Prado, "The Deflated Sharpe Ratio" (2014), eq. for E[max].
+ */
+export function sweepHaircut({ numTrials, sharpeStd }) {
+  const N = Math.max(1, numTrials);
+  const a = normalPpf(1 - 1 / N);
+  const b = normalPpf(1 - 1 / (N * Math.E));
+  const expectedMaxSharpe = sharpeStd * ((1 - EULER_MASCHERONI) * a + EULER_MASCHERONI * b);
+  return { expectedMaxSharpe, numTrials: N };
+}
+
+/**
+ * Deflated Sharpe Ratio: probability the observed `sharpe` (per-period, not
+ * annualized) is genuinely > 0 after accounting for `numTrials` selections,
+ * non-normal returns (skew, kurtosis), and finite `sampleSize`.
+ * Returns a probability in [0,1]; below ~0.95 means "not convincingly real."
+ */
+export function deflatedSharpe({
+  sharpe,
+  sampleSize,
+  numTrials = 1,
+  sharpeStd = 0,
+  skew = 0,
+  kurtosis = 3,
+}) {
+  const sr0 = sweepHaircut({ numTrials, sharpeStd }).expectedMaxSharpe;
+  const denom = Math.sqrt(
+    Math.max(1e-12, 1 - skew * sharpe + ((kurtosis - 1) / 4) * sharpe * sharpe)
+  );
+  const z = ((sharpe - sr0) * Math.sqrt(Math.max(1, sampleSize - 1))) / denom;
+  return normalCdf(z);
+}
+```
+
+- [ ] **Step 5: Run to verify it passes**
+
+Run: `node --test test/research/deflatedSharpe.test.js`
+Expected: PASS (3 tests).
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/research/stats.js src/research/deflatedSharpe.js test/research/deflatedSharpe.test.js
+git commit -m "feat: add normal stats, deflated Sharpe, sweep haircut
+
+Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 4: Probability of Backtest Overfitting (CSCV)
+
+**Files:**
+
+- Create: `src/research/combinations.js`
+- Create: `src/research/pbo.js`
+- Test: `test/research/pbo.test.js`
+
+- [ ] **Step 1: Write the failing test**
+
+```js
+// test/research/pbo.test.js
+import test from "node:test";
+import assert from "node:assert/strict";
+import { combinations } from "../../src/research/combinations.js";
+import { probabilityOfBacktestOverfitting } from "../../src/research/pbo.js";
+
+test("combinations(4,2) yields 6 unique index pairs", () => {
+  const combos = combinations(4, 2);
+  assert.equal(combos.length, 6);
+  assert.deepEqual(combos[0], [0, 1]);
+});
+
+test("a single dominant strategy gives low PBO", () => {
+  // strategy 0 always best; 8 observations, matrix [strategy][observation]
+  const obs = 8;
+  const winner = Array.from({ length: obs }, () => 5);
+  const loser1 = Array.from({ length: obs }, (_, i) => (i % 2 ? 1 : -1));
+  const loser2 = Array.from({ length: obs }, (_, i) => (i % 3 ? 0.5 : -0.5));
+  const out = probabilityOfBacktestOverfitting([winner, loser1, loser2], { groups: 4 });
+  assert.ok(out.pbo <= 0.25);
+  assert.equal(out.combos > 0, true);
+});
+
+test("noise strategies give PBO near 0.5", () => {
+  const obs = 12;
+  const mk = (seed) => Array.from({ length: obs }, (_, i) => Math.sin(seed * 7.1 + i * 1.3));
+  const matrix = [mk(1), mk(2), mk(3), mk(4), mk(5)];
+  const out = probabilityOfBacktestOverfitting(matrix, { groups: 6 });
+  assert.ok(out.pbo >= 0.2 && out.pbo <= 0.8);
+});
+```
+
+- [ ] **Step 2: Run to verify it fails**
+
+Run: `node --test test/research/pbo.test.js`
+Expected: FAIL — cannot find modules.
+
+- [ ] **Step 3: Implement src/research/combinations.js**
+
+```js
+// src/research/combinations.js
+
+/** All k-sized index combinations of [0..n). Returns arrays of indices. */
+export function combinations(n, k) {
+  const result = [];
+  const combo = [];
+  function recurse(start) {
+    if (combo.length === k) {
+      result.push([...combo]);
+      return;
+    }
+    for (let i = start; i < n; i += 1) {
+      combo.push(i);
+      recurse(i + 1);
+      combo.pop();
+    }
+  }
+  recurse(0);
+  return result;
+}
+```
+
+- [ ] **Step 4: Implement src/research/pbo.js**
+
+```js
+// src/research/pbo.js
+import { combinations } from "./combinations.js";
+
+function sharpeOf(returns) {
+  const n = returns.length;
+  if (n < 2) return 0;
+  const mean = returns.reduce((a, b) => a + b, 0) / n;
+  let variance = 0;
+  for (const r of returns) variance += (r - mean) ** 2;
+  variance /= n - 1;
+  const std = Math.sqrt(variance);
+  return std === 0 ? 0 : mean / std;
+}
+
+/**
+ * Combinatorially-Symmetric Cross-Validation estimate of the Probability of
+ * Backtest Overfitting (Bailey, Borwein, López de Prado, Zhu 2017).
+ *
+ * `performanceMatrix` is [nStrategies][nObservations] of per-period returns.
+ * Observations are split into `groups` equal slices; every way of choosing
+ * half the groups forms the in-sample (IS) set, the rest out-of-sample (OS).
+ * For each split: pick the best strategy IS (by Sharpe), find its OS rank;
+ * PBO = fraction of splits where the IS winner lands in the bottom half OS.
+ */
+export function probabilityOfBacktestOverfitting(performanceMatrix, { groups = 16 } = {}) {
+  const nStrategies = performanceMatrix.length;
+  if (nStrategies < 2) throw new Error("PBO needs at least 2 strategies");
+  const nObs = performanceMatrix[0].length;
+  const S = Math.min(groups, nObs);
+  if (S % 2 !== 0) throw new Error("groups must be even");
+
+  // Partition observation indices into S contiguous groups.
+  const groupIdx = Array.from({ length: S }, () => []);
+  for (let i = 0; i < nObs; i += 1) groupIdx[Math.floor((i * S) / nObs)].push(i);
+
+  const isCombos = combinations(S, S / 2);
+  const logits = [];
+  let overfitCount = 0;
+
+  for (const isGroups of isCombos) {
+    const isSet = new Set(isGroups);
+    const isIndices = [];
+    const osIndices = [];
+    for (let g = 0; g < S; g += 1) {
+      (isSet.has(g) ? isIndices : osIndices).push(...groupIdx[g]);
+    }
+
+    const isScores = performanceMatrix.map((row) => sharpeOf(isIndices.map((i) => row[i])));
+    const osScores = performanceMatrix.map((row) => sharpeOf(osIndices.map((i) => row[i])));
+
+    let bestStrategy = 0;
+    for (let s = 1; s < nStrategies; s += 1) {
+      if (isScores[s] > isScores[bestStrategy]) bestStrategy = s;
+    }
+
+    // OS rank of the IS winner (1 = worst .. N = best)
+    const winnerOs = osScores[bestStrategy];
+    let rank = 1;
+    for (let s = 0; s < nStrategies; s += 1) {
+      if (s !== bestStrategy && osScores[s] < winnerOs) rank += 1;
+    }
+    const relativeRank = rank / (nStrategies + 1); // in (0,1)
+    const logit = Math.log(relativeRank / (1 - relativeRank));
+    logits.push(logit);
+    if (relativeRank <= 0.5) overfitCount += 1;
+  }
+
+  return {
+    pbo: overfitCount / isCombos.length,
+    combos: isCombos.length,
+    medianLogit: [...logits].sort((a, b) => a - b)[Math.floor(logits.length / 2)],
+  };
+}
+```
+
+- [ ] **Step 5: Run to verify it passes**
+
+Run: `node --test test/research/pbo.test.js`
+Expected: PASS (3 tests). If the "noise" test is flaky at the boundary, widen the
+band assertion to `[0.15, 0.85]` — PBO of pure noise is ~0.5 in expectation but
+varies with the deterministic sample.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/research/combinations.js src/research/pbo.js test/research/pbo.test.js
+git commit -m "feat: add CSCV probability of backtest overfitting
+
+Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 5: Combinatorial Purged Cross-Validation splits
+
+**Files:**
+
+- Create: `src/research/cpcv.js`
+- Test: `test/research/cpcv.test.js`
+
+- [ ] **Step 1: Write the failing test**
+
+```js
+// test/research/cpcv.test.js
+import test from "node:test";
+import assert from "node:assert/strict";
+import { combinatorialPurgedSplits } from "../../src/research/cpcv.js";
+
+test("cpcv produces C(nGroups, nTestGroups) splits with disjoint train/test", () => {
+  const splits = combinatorialPurgedSplits({
+    nObservations: 100,
+    nGroups: 6,
+    nTestGroups: 2,
+    embargo: 0,
+  });
+  // C(6,2) = 15
+  assert.equal(splits.length, 15);
+  for (const { train, test: testIdx } of splits) {
+    const trainSet = new Set(train);
+    for (const t of testIdx) assert.equal(trainSet.has(t), false);
+  }
+});
+
+test("embargo removes train observations adjacent to test blocks", () => {
+  const noEmbargo = combinatorialPurgedSplits({
+    nObservations: 60,
+    nGroups: 6,
+    nTestGroups: 1,
+    embargo: 0,
+  });
+  const withEmbargo = combinatorialPurgedSplits({
+    nObservations: 60,
+    nGroups: 6,
+    nTestGroups: 1,
+    embargo: 3,
+  });
+  // embargo can only shrink (or keep equal) the train set
+  assert.ok(withEmbargo[0].train.length <= noEmbargo[0].train.length);
+});
+```
+
+- [ ] **Step 2: Run to verify it fails**
+
+Run: `node --test test/research/cpcv.test.js`
+Expected: FAIL — cannot find module.
+
+- [ ] **Step 3: Implement src/research/cpcv.js**
+
+```js
+// src/research/cpcv.js
+import { combinations } from "./combinations.js";
+
+/**
+ * Combinatorial Purged Cross-Validation index splits (López de Prado,
+ * "Advances in Financial Machine Learning", ch. 12).
+ *
+ * Splits [0..nObservations) into `nGroups` contiguous blocks, then forms every
+ * combination choosing `nTestGroups` blocks as the test set. Training indices
+ * that fall within `embargo` observations of any test block are purged to avoid
+ * leakage from overlapping/serially-correlated samples.
+ *
+ * Returns [{ train: number[], test: number[] }].
+ */
+export function combinatorialPurgedSplits({
+  nObservations,
+  nGroups = 6,
+  nTestGroups = 2,
+  embargo = 0,
+}) {
+  if (!(nObservations > 0)) throw new Error("nObservations must be positive");
+  if (nTestGroups >= nGroups) throw new Error("nTestGroups must be < nGroups");
+
+  const bounds = [];
+  for (let g = 0; g < nGroups; g += 1) {
+    bounds.push([
+      Math.floor((g * nObservations) / nGroups),
+      Math.floor(((g + 1) * nObservations) / nGroups),
+    ]);
+  }
+
+  const splits = [];
+  for (const testGroups of combinations(nGroups, nTestGroups)) {
+    const testSet = new Set();
+    const purgeZones = [];
+    for (const g of testGroups) {
+      const [start, end] = bounds[g];
+      for (let i = start; i < end; i += 1) testSet.add(i);
+      purgeZones.push([start - embargo, end + embargo]);
+    }
+    const inPurge = (i) => purgeZones.some(([lo, hi]) => i >= lo && i < hi);
+
+    const train = [];
+    const testIdx = [];
+    for (let i = 0; i < nObservations; i += 1) {
+      if (testSet.has(i)) testIdx.push(i);
+      else if (!inPurge(i)) train.push(i);
+    }
+    splits.push({ train, test: testIdx, testGroups });
+  }
+  return splits;
+}
+```
+
+- [ ] **Step 4: Run to verify it passes**
+
+Run: `node --test test/research/cpcv.test.js`
+Expected: PASS (2 tests).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/research/cpcv.js test/research/cpcv.test.js
+git commit -m "feat: add combinatorial purged cross-validation splits
+
+Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 6: Aggregate `research` namespace + export + docs
+
+**Files:**
+
+- Create: `src/research/index.js`
+- Modify: `src/index.js`
+- Create: `docs/research.md`
+- Modify: `README.md` (link the new guide)
+
+- [ ] **Step 1: Write the failing test**
+
+```js
+// test/research/index.test.js
+import test from "node:test";
+import assert from "node:assert/strict";
+import { research } from "../../src/index.js";
+
+test("research namespace exposes the full toolkit", () => {
+  for (const fn of [
+    "monteCarlo",
+    "deflatedSharpe",
+    "sweepHaircut",
+    "probabilityOfBacktestOverfitting",
+    "combinatorialPurgedSplits",
+  ]) {
+    assert.equal(typeof research[fn], "function", `missing research.${fn}`);
+  }
+});
+```
+
+- [ ] **Step 2: Run to verify it fails**
+
+Run: `node --test test/research/index.test.js`
+Expected: FAIL — `research` is not exported from `src/index.js`.
+
+- [ ] **Step 3: Create src/research/index.js**
+
+```js
+// src/research/index.js
+export { monteCarlo } from "./monteCarlo.js";
+export { deflatedSharpe, sweepHaircut } from "./deflatedSharpe.js";
+export { probabilityOfBacktestOverfitting } from "./pbo.js";
+export { combinatorialPurgedSplits } from "./cpcv.js";
+export { combinations } from "./combinations.js";
+export { normalCdf, normalPpf, moments } from "./stats.js";
+```
+
+- [ ] **Step 4: Export from src/index.js**
+
+Add near the other exports:
+
+```js
+export * as research from "./research/index.js";
+```
+
+- [ ] **Step 5: Run test + full suite**
+
+Run: `node --test test/research/index.test.js`
+Expected: PASS.
+
+Run: `node --test`
+Expected: PASS.
+
+- [ ] **Step 6: Write docs/research.md**
+
+Document each function: signature, inputs, return shape, and a worked example
+that takes a `backtest()` result and runs the kit:
+
+```js
+import { backtest, research } from "tradelab";
+
+const result = backtest({ candles, interval: "1d", signal });
+const pnls = result.positions.map((p) => p.exit.pnl);
+
+const mc = research.monteCarlo({ tradePnls: pnls, equityStart: 10_000, seed: 1 });
+console.log("5% worst final equity:", mc.finalEquity.p5);
+
+const dsr = research.deflatedSharpe({
+  sharpe: result.metrics.sharpeDaily,
+  sampleSize: result.metrics.trades,
+  numTrials: 20, // how many parameter sets you tried
+  sharpeStd: 0.5, // dispersion of Sharpe across those trials
+  skew: 0,
+  kurtosis: 3,
+});
+console.log("Deflated Sharpe prob:", dsr);
+```
+
+Include a paragraph explaining how to feed a parameter-sweep's per-set return
+series into `probabilityOfBacktestOverfitting` (rows = parameter sets, columns =
+per-period returns) and how to read PBO (> 0.5 means the selection process is
+likely overfit).
+
+- [ ] **Step 7: Link from README + lint + commit**
+
+Add a row to the README documentation table:
+
+```markdown
+| [Research & overfitting](docs/research.md) | Monte Carlo, deflated Sharpe, PBO, CPCV, sweep haircut |
+```
+
+```bash
+npm run lint && npm run format:check && npm test
+git add src/research/index.js src/index.js docs/research.md README.md test/research/index.test.js
+git commit -m "feat: expose research toolkit namespace and docs
+
+Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
+```
+
+---
+
+## Self-review checklist
+
+- [ ] All randomness flows through `makeRng(seed)` — Monte Carlo is reproducible. ✔ (Tasks 1, 2)
+- [ ] `combinations` is shared by both `pbo.js` and `cpcv.js` (DRY). ✔
+- [ ] Function names are consistent: `monteCarlo`, `deflatedSharpe`, `sweepHaircut`, `probabilityOfBacktestOverfitting`, `combinatorialPurgedSplits` appear identically in implementation, index, test, and docs. ✔
+- [ ] No engine files modified — toolkit is pure and decoupled. ✔
+- [ ] `src/utils/random.js` content is byte-identical to Plan 4's version (shared file). ✔ (Task 1 Step 3)