tradelab 1.1.0 → 1.2.0

package/docs/superpowers/plans/2026-06-parallel-param-sweep.md

@@ -1,508 +0,0 @@
-# Parallel Parameter Sweep 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:** Turn large parameter sweeps from serial-and-slow into parallel-and-fast with a `worker_threads` pool, exposed as `optimize()`, returning a scored leaderboard.
-
-**Architecture:** Functions can't cross the worker boundary, so the signal is supplied as a **module path** exporting `createSignal(params)` (each worker dynamically imports it once). The main thread owns a pool of N workers, streams parameter-set indices to idle workers, and collects metric summaries. Candles are passed once per worker via `workerData`. A `grid()` helper expands `{ key: value[] }` into parameter sets.
-
-**Tech Stack:** Node ESM `worker_threads` (built-in), `node:os`, `node:test`. No new dependencies. Independent of other plans (integrates with Plan 5's registry if present, but does not require it).
-
----
-
-### Task 1: Grid expansion helper
-
-**Files:**
-
-- Create: `src/engine/grid.js`
-- Test: `test/engine/grid.test.js`
-
-- [ ] **Step 1: Write the failing test**
-
-```js
-// test/engine/grid.test.js
-import test from "node:test";
-import assert from "node:assert/strict";
-import { grid } from "../../src/engine/grid.js";
-
-test("grid expands a cartesian product in stable order", () => {
-  const sets = grid({ fast: [3, 5], slow: [8, 13] });
-  assert.equal(sets.length, 4);
-  assert.deepEqual(sets[0], { fast: 3, slow: 8 });
-  assert.deepEqual(sets[3], { fast: 5, slow: 13 });
-});
-
-test("grid of an empty spec yields a single empty set", () => {
-  assert.deepEqual(grid({}), [{}]);
-});
-
-test("grid passes scalar (non-array) values through as fixed", () => {
-  const sets = grid({ fast: [3, 5], rr: 2 });
-  assert.equal(sets.length, 2);
-  assert.equal(sets[0].rr, 2);
-  assert.equal(sets[1].rr, 2);
-});
-```
-
-- [ ] **Step 2: Run to verify it fails**
-
-Run: `node --test test/engine/grid.test.js`
-Expected: FAIL — cannot find module.
-
-- [ ] **Step 3: Implement src/engine/grid.js**
-
-```js
-// src/engine/grid.js
-
-/**
- * Expand a parameter grid into an array of parameter-set objects.
- * Array values are swept; scalar values are held fixed across all sets.
- *   grid({ fast: [3,5], slow: [8,13], rr: 2 })
- *   => [{fast:3,slow:8,rr:2}, {fast:3,slow:13,rr:2}, {fast:5,slow:8,rr:2}, {fast:5,slow:13,rr:2}]
- */
-export function grid(spec = {}) {
-  const keys = Object.keys(spec);
-  if (!keys.length) return [{}];
-  return keys.reduce(
-    (acc, key) => {
-      const values = Array.isArray(spec[key]) ? spec[key] : [spec[key]];
-      return acc.flatMap((base) => values.map((v) => ({ ...base, [key]: v })));
-    },
-    [{}]
-  );
-}
-```
-
-- [ ] **Step 4: Run to verify it passes**
-
-Run: `node --test test/engine/grid.test.js`
-Expected: PASS (3 tests).
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add src/engine/grid.js test/engine/grid.test.js
-git commit -m "feat: add parameter grid expansion helper
-
-Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
-```
-
----
-
-### Task 2: The worker
-
-**Files:**
-
-- Create: `src/engine/optimizeWorker.js`
-- Test: `test/fixtures/emaSignal.js` (fixture used by Task 3's test)
-
-- [ ] **Step 1: Create the test fixture (a serializable signal module)**
-
-```js
-// test/fixtures/emaSignal.js
-import { ema } from "../../src/utils/indicators.js";
-
-export function createSignal({ fast = 10, slow = 30, rr = 2 } = {}) {
-  return ({ candles, bar }) => {
-    if (candles.length < slow + 2) return null;
-    const closes = candles.map((c) => c.close);
-    const f = ema(closes, fast);
-    const s = ema(closes, slow);
-    const i = closes.length - 1;
-    if (f[i - 1] <= s[i - 1] && f[i] > s[i]) {
-      const stop = Math.min(...candles.slice(-15).map((c) => c.low));
-      if (stop >= bar.close) return null;
-      return { side: "long", entry: bar.close, stop, rr };
-    }
-    return null;
-  };
-}
-```
-
-- [ ] **Step 2: Implement src/engine/optimizeWorker.js**
-
-```js
-// src/engine/optimizeWorker.js
-import { workerData, parentPort } from "node:worker_threads";
-import { pathToFileURL } from "node:url";
-import { backtest } from "./backtest.js";
-
-const { candles, signalModulePath, interval, backtestOptions } = workerData;
-
-const mod = await import(pathToFileURL(signalModulePath).href);
-const createSignal = mod.createSignal ?? mod.default;
-if (typeof createSignal !== "function") {
-  throw new Error(
-    `optimize: ${signalModulePath} must export createSignal(params) or a default factory`
-  );
-}
-
-// Only ship the metric fields a sweep ranks on — keep IPC payloads tiny.
-function pickMetrics(metrics) {
-  const keep = [
-    "trades",
-    "winRate",
-    "profitFactor",
-    "expectancy",
-    "totalR",
-    "avgR",
-    "sharpe",
-    "sharpeAnnualized",
-    "maxDrawdown",
-    "calmar",
-    "returnPct",
-    "totalPnL",
-    "finalEquity",
-  ];
-  const out = {};
-  for (const k of keep) out[k] = metrics[k];
-  return out;
-}
-
-parentPort.on("message", (msg) => {
-  if (msg.type === "stop") {
-    process.exit(0);
-  }
-  if (msg.type === "run") {
-    try {
-      const result = backtest({
-        candles,
-        interval,
-        signal: createSignal(msg.params),
-        collectReplay: false,
-        collectEqSeries: false,
-        ...backtestOptions,
-      });
-      parentPort.postMessage({
-        type: "result",
-        index: msg.index,
-        params: msg.params,
-        metrics: pickMetrics(result.metrics),
-      });
-    } catch (error) {
-      parentPort.postMessage({
-        type: "error",
-        index: msg.index,
-        params: msg.params,
-        error: error instanceof Error ? error.message : String(error),
-      });
-    }
-  }
-});
-
-parentPort.postMessage({ type: "ready" });
-```
-
-- [ ] **Step 3: Commit**
-
-```bash
-git add src/engine/optimizeWorker.js test/fixtures/emaSignal.js
-git commit -m "feat: add backtest sweep worker
-
-Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
-```
-
----
-
-### Task 3: The pool — `optimize()`
-
-**Files:**
-
-- Create: `src/engine/optimize.js`
-- Modify: `src/index.js`
-- Test: `test/optimize.test.js`
-
-- [ ] **Step 1: Write the failing test**
-
-```js
-// test/optimize.test.js
-import test from "node:test";
-import assert from "node:assert/strict";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-import { optimize, grid } from "../src/index.js";
-
-const here = path.dirname(fileURLToPath(import.meta.url));
-const signalModulePath = path.join(here, "fixtures", "emaSignal.js");
-
-function buildCandles(n = 120) {
-  const start = Date.UTC(2025, 0, 2, 14, 30, 0);
-  return Array.from({ length: n }, (_, i) => ({
-    time: start + i * 86_400_000,
-    open: 100 + Math.sin(i / 4) * 5,
-    high: 102 + Math.sin(i / 4) * 5,
-    low: 98 + Math.sin(i / 4) * 5,
-    close: 100 + Math.sin(i / 4) * 5,
-    volume: 1000,
-  }));
-}
-
-test("optimize runs every parameter set and returns a ranked leaderboard", async () => {
-  const candles = buildCandles();
-  const parameterSets = grid({ fast: [3, 5, 8], slow: [13, 21] });
-  const out = await optimize({
-    candles,
-    interval: "1d",
-    signalModulePath,
-    parameterSets,
-    concurrency: 2,
-    scoreBy: "profitFactor",
-  });
-  assert.equal(out.results.length, parameterSets.length);
-  assert.ok(out.leaderboard.length >= 1);
-  // leaderboard is sorted descending by score
-  for (let i = 1; i < out.leaderboard.length; i += 1) {
-    assert.ok(
-      out.leaderboard[i - 1].metrics.profitFactor >= out.leaderboard[i].metrics.profitFactor
-    );
-  }
-  assert.equal(out.best, out.leaderboard[0]);
-});
-
-test("optimize matches a serial baseline for the same params", async () => {
-  const candles = buildCandles();
-  const parameterSets = grid({ fast: [5], slow: [21] });
-  const parallel = await optimize({
-    candles,
-    interval: "1d",
-    signalModulePath,
-    parameterSets,
-    concurrency: 1,
-  });
-  const { backtest } = await import("../src/index.js");
-  const { createSignal } = await import("./fixtures/emaSignal.js");
-  const serial = backtest({
-    candles,
-    interval: "1d",
-    signal: createSignal(parameterSets[0]),
-    collectReplay: false,
-    collectEqSeries: false,
-  });
-  assert.equal(parallel.results[0].metrics.totalPnL, serial.metrics.totalPnL);
-});
-```
-
-- [ ] **Step 2: Run to verify it fails**
-
-Run: `node --test test/optimize.test.js`
-Expected: FAIL — `optimize` not exported.
-
-- [ ] **Step 3: Implement src/engine/optimize.js**
-
-```js
-// src/engine/optimize.js
-import { Worker } from "node:worker_threads";
-import os from "node:os";
-
-function defaultConcurrency() {
-  return Math.max(1, (os.cpus()?.length ?? 2) - 1);
-}
-
-function scoreValue(metrics, scoreBy) {
-  const v = metrics?.[scoreBy];
-  return Number.isFinite(v) ? v : -Infinity;
-}
-
-/**
- * Parallel parameter sweep over a worker pool.
- *
- * @param {object} opts
- * @param {Array} opts.candles            OHLCV candles (copied once per worker)
- * @param {string} opts.signalModulePath  absolute path to a module exporting createSignal(params)
- * @param {Array<object>} opts.parameterSets  parameter objects (use grid() to build)
- * @param {string} [opts.interval]
- * @param {object} [opts.backtestOptions]
- * @param {number} [opts.concurrency]     defaults to cpus-1
- * @param {string} [opts.scoreBy="profitFactor"]
- * @returns {Promise<{results, leaderboard, best}>}
- */
-export function optimize({
-  candles,
-  signalModulePath,
-  parameterSets,
-  interval,
-  backtestOptions = {},
-  concurrency,
-  scoreBy = "profitFactor",
-}) {
-  if (!Array.isArray(parameterSets) || parameterSets.length === 0) {
-    return Promise.resolve({ results: [], leaderboard: [], best: null });
-  }
-
-  return new Promise((resolve, reject) => {
-    const poolSize = Math.min(concurrency || defaultConcurrency(), parameterSets.length);
-    const results = new Array(parameterSets.length);
-    const workers = [];
-    let nextIndex = 0;
-    let completed = 0;
-    let settled = false;
-
-    const finish = () => {
-      if (settled) return;
-      settled = true;
-      for (const w of workers) w.terminate();
-      const ranked = results
-        .filter((r) => r && r.metrics)
-        .sort((a, b) => scoreValue(b.metrics, scoreBy) - scoreValue(a.metrics, scoreBy));
-      resolve({ results, leaderboard: ranked, best: ranked[0] ?? null });
-    };
-
-    const fail = (error) => {
-      if (settled) return;
-      settled = true;
-      for (const w of workers) w.terminate();
-      reject(error);
-    };
-
-    const dispatch = (worker) => {
-      if (nextIndex >= parameterSets.length) {
-        worker.postMessage({ type: "stop" });
-        return;
-      }
-      const index = nextIndex;
-      nextIndex += 1;
-      worker.postMessage({ type: "run", index, params: parameterSets[index] });
-    };
-
-    for (let i = 0; i < poolSize; i += 1) {
-      const worker = new Worker(new URL("./optimizeWorker.js", import.meta.url), {
-        workerData: { candles, signalModulePath, interval, backtestOptions },
-      });
-      workers.push(worker);
-
-      worker.on("message", (msg) => {
-        if (msg.type === "ready") {
-          dispatch(worker);
-          return;
-        }
-        if (msg.type === "result" || msg.type === "error") {
-          results[msg.index] =
-            msg.type === "result"
-              ? { params: msg.params, metrics: msg.metrics }
-              : { params: msg.params, error: msg.error };
-          completed += 1;
-          if (completed === parameterSets.length) finish();
-          else dispatch(worker);
-        }
-      });
-
-      worker.on("error", fail);
-    }
-  });
-}
-```
-
-- [ ] **Step 4: Export from src/index.js**
-
-```js
-export { optimize } from "./engine/optimize.js";
-export { grid } from "./engine/grid.js";
-```
-
-- [ ] **Step 5: Run test + full suite**
-
-Run: `node --test test/optimize.test.js`
-Expected: PASS (2 tests).
-
-Run: `node --test`
-Expected: PASS.
-
-- [ ] **Step 6: Lint + commit**
-
-```bash
-npm run lint
-git add src/engine/optimize.js src/index.js test/optimize.test.js
-git commit -m "feat: parallel parameter sweep via worker pool
-
-Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
-```
-
----
-
-### Task 4: Build compatibility + docs
-
-**Files:**
-
-- Modify: `scripts/build-cjs.mjs` (ensure the worker file ships)
-- Modify: `docs/backtest-engine.md`
-- Create: `examples/optimize.js`
-
-- [ ] **Step 1: Confirm worker file ships in the package**
-
-`optimizeWorker.js` is under `src/`, which is already in `package.json`'s `files`
-array, so it ships. The CJS build does NOT need a separate bundle for the worker —
-worker_threads is used from the ESM `src/` path. Verify the file is present after
-a pack dry-run:
-
-Run: `npm pack --dry-run | grep optimizeWorker`
-Expected: `src/engine/optimizeWorker.js` appears in the listing.
-
-Note for the CJS consumer: `optimize()` spawns an ESM worker via
-`new URL("./optimizeWorker.js", import.meta.url)`. If the CJS build path breaks
-`import.meta.url`, document that `optimize()` is ESM-only (acceptable v1 scope) in
-the build script comments and the docs.
-
-- [ ] **Step 2: Write examples/optimize.js**
-
-```js
-// examples/optimize.js
-// Run: node examples/optimize.js
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-import { optimize, grid, getHistoricalCandles } from "../src/index.js";
-
-const here = path.dirname(fileURLToPath(import.meta.url));
-
-const candles = await getHistoricalCandles({
-  source: "yahoo",
-  symbol: "SPY",
-  interval: "1d",
-  period: "2y",
-  cache: true,
-});
-
-const { leaderboard, best } = await optimize({
-  candles,
-  interval: "1d",
-  // a module exporting createSignal(params)
-  signalModulePath: path.join(here, "..", "test", "fixtures", "emaSignal.js"),
-  parameterSets: grid({ fast: [5, 8, 10, 12], slow: [20, 30, 50] }),
-  scoreBy: "sharpeAnnualized",
-});
-
-console.log("best params:", best?.params, "sharpe:", best?.metrics.sharpeAnnualized);
-console.table(leaderboard.slice(0, 5).map((r) => ({ ...r.params, ...r.metrics })));
-```
-
-- [ ] **Step 3: Run the example**
-
-Run: `node examples/optimize.js`
-Expected: prints a leaderboard table (network permitting). On a multi-core machine
-this completes far faster than a serial loop over the same 12-set grid.
-
-- [ ] **Step 4: Document in docs/backtest-engine.md**
-
-Add an "Optimization (parallel sweeps)" section: the `signalModulePath` contract
-(`export function createSignal(params)`), the `grid()` helper, `concurrency`,
-`scoreBy`, the leaderboard shape, and the ESM-only caveat for `optimize()`.
-
-- [ ] **Step 5: Lint, format, test, commit**
-
-```bash
-npm run lint && npm run format:check && npm test
-git add scripts/build-cjs.mjs docs/backtest-engine.md examples/optimize.js
-git commit -m "docs: parallel optimize example and guide
-
-Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
-```
-
----
-
-## Self-review checklist
-
-- [ ] Signal crosses the worker boundary as a module path, not a function (workers can't receive closures). ✔ (Task 2)
-- [ ] Candles copied once per worker via `workerData`, not per parameter set. ✔ (Task 3)
-- [ ] Pool drains correctly: `dispatch` posts `stop` when no sets remain; `finish`/`fail` are idempotent via the `settled` guard; all workers terminated. ✔
-- [ ] Parallel result is asserted equal to the serial baseline for identical params. ✔ (Task 3 Step 1)
-- [ ] IPC payloads carry only ranking metrics, not full trade logs/replay. ✔ (Task 2 `pickMetrics`)
-- [ ] ESM-only limitation of `optimize()` is documented. ✔ (Task 4)