tradelab 1.0.0 → 1.1.0

package/docs/backtest-engine.md

@@ -5,6 +5,7 @@
 This page covers the simulation layer:
 
 - `backtest(options)`
+- `backtestAsync(options)`
 - `backtestTicks(options)`
 - `backtestPortfolio(options)`
 - `walkForwardOptimize(options)`
@@ -21,6 +22,7 @@ The same `signal()` contract is used by `LiveEngine` in `tradelab/live`, so stra
 | Use case                                  | Function                |
 | ----------------------------------------- | ----------------------- |
 | One strategy on one candle series         | `backtest()`            |
+| Async or model-backed candle signal       | `backtestAsync()`       |
 | One strategy on tick or quote data        | `backtestTicks()`       |
 | Multiple symbols with one combined result | `backtestPortfolio()`   |
 | Rolling or anchored train/test validation | `walkForwardOptimize()` |
@@ -127,6 +129,43 @@ Return `null` for no trade, or a signal object:
 
 Practical rule: return the smallest signal object that expresses the trade clearly. In many strategies that is just `side`, `stop`, and `rr`.
 
+## Async signals
+
+Use `backtestAsync()` when `signal()` returns a promise, such as an LLM call, agent decision, remote service lookup, or any async feature computation.
+
+```js
+import { backtestAsync, LlmSignal } from "tradelab";
+
+const llm = new LlmSignal({
+  budgetMs: 2000,
+  onError: "skip",
+  async resolve({ candles, bar }) {
+    const recent = candles.slice(-5);
+    return recent.every((c, i) => i === 0 || c.close >= recent[i - 1].close)
+      ? { side: "long", stop: bar.close * 0.98, rr: 2 }
+      : null;
+  },
+});
+
+const result = await backtestAsync({
+  candles,
+  signal: llm.signal,
+  signalBudgetMs: 3000,
+});
+```
+
+`backtestAsync()` returns the same result shape as `backtest()`. `signalBudgetMs` races each signal call against a per-bar deadline; set it to `0` or omit it to disable the timeout.
+
+`LlmSignal` is an optional wrapper for model-backed decisions:
+
+- caches by bar time, so repeated calls for one bar reuse the same decision
+- passes a no-lookahead candle view into `resolve()`
+- enforces `budgetMs` with the same timeout primitive as `backtestAsync()`
+- records each result or error in `llm.log`
+- returns `null` on errors by default, or rethrows with `onError: "throw"`
+
+Live trading also awaits async signals; see [live trading](live-trading.md).
+
 ### Optional per-trade hints
 
 These values are read from the signal object when present:
@@ -164,6 +203,15 @@ For more control, use `costs`:
     commissionPerUnit: 0,
     commissionPerOrder: 1,
     minCommission: 1,
+    carry: {
+      longAnnualBps: 500,
+      shortAnnualBps: 800,
+    },
+    funding: {
+      rateBps: 10,
+      intervalMs: 8 * 60 * 60 * 1000,
+      anchorMs: 0,
+    },
   },
 }
 ```
@@ -174,9 +222,13 @@ For more control, use `costs`:
 - spread is modeled as half-spread paid on entry and exit
 - commission can be percentage-based, per-unit, per-order, or mixed
 - `minCommission` floors the fee for that fill
+- `carry.longAnnualBps` and `carry.shortAnnualBps` are annualized financing or borrow rates deducted when each leg closes
+- `funding.rateBps` applies once per funding boundary in `(openTime, closeTime]`; positive rates charge longs and credit shorts
 
 This is still a bar-based simulation. It does not model queue position, exchange microstructure, or realistic intrabar order priority.
 
+Closed trades expose the time-based charge as `trade.exit.financing`. It is already included in `trade.exit.pnl` and aggregate metrics, so use it only when you need attribution.
+
 ### Advanced trade management
 
 These are optional. Ignore them until the strategy actually needs them.
@@ -248,6 +300,18 @@ Useful first checks after any run:
 - `metrics.maxDrawdown`: whether the path is survivable
 - `metrics.sideBreakdown`: whether one side carries the result
 
+### 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()`.
+
 ### `eqSeries`
 
 Realized equity points:
@@ -309,6 +373,7 @@ Use tick mode when you want event-driven fills while keeping the same result sha
 const result = backtestTicks({
   ticks,
   queueFillProbability: 0.5,
+  seed: "experiment-42",
   signal,
 });
 ```
@@ -317,6 +382,7 @@ const result = backtestTicks({
 
 - market entries fill on the next tick
 - limit orders can fill at the touch based on `queueFillProbability`
+- identical `seed` + data + options produce identical probabilistic limit-fill outcomes
 - stop exits fill at the stop and use the normal stop slippage model from `costs.slippageByKind.stop`
 - results still come back as `trades`, `positions`, `metrics`, `eqSeries`, and `replay`
 
@@ -358,6 +424,52 @@ const wf = walkForwardOptimize({
 
 In practice, the per-window output matters more than the aggregate headline. If the winning parameters swing wildly from one window to the next, treat that as a real signal.
 
+## Optimization (parallel sweeps)
+
+Use `optimize()` for large parameter sweeps that can run independently across a worker pool.
+
+```js
+import path from "node:path";
+import { optimize, grid } from "tradelab";
+
+const out = await optimize({
+  candles,
+  interval: "1d",
+  signalModulePath: path.resolve("./strategies/emaSignal.js"),
+  parameterSets: grid({ fast: [5, 8, 10], slow: [20, 30, 50], rr: 2 }),
+  concurrency: 4,
+  scoreBy: "sharpeAnnualized",
+});
+
+console.log(out.best?.params, out.best?.metrics);
+```
+
+`signalModulePath` must point to an ESM module that exports `createSignal(params)` or a default factory:
+
+```js
+export function createSignal(params) {
+  return function signal(context) {
+    return null;
+  };
+}
+```
+
+Functions cannot cross the worker boundary, so the signal is passed as a module path plus JSON-like parameter objects. Candles are copied once per worker, not once per parameter set.
+
+The return shape is:
+
+```js
+{
+  (results, // original order, one entry per parameter set
+    leaderboard, // sorted descending by scoreBy
+    best); // leaderboard[0] or null
+}
+```
+
+Each result contains `{ params, metrics }` or `{ params, error }`. Worker IPC only returns compact ranking metrics, not trade logs or replay frames.
+
+`optimize()` is ESM-only in this release because it starts an ESM `worker_threads` worker via `import.meta.url`. Use it from ESM code, for example `node examples/optimize.js`.
+
 ## `buildMetrics(input)`
 
 Most users do not need this directly. Use it when:

package/docs/live-trading.md

@@ -63,10 +63,35 @@ await engine.stop();
 Important behavior:
 
 - `signal()` is called with the same context shape as backtesting
+- `signal()` may be async; `LiveEngine` awaits the decision before normalizing it
 - market and limit/stop order lifecycles are tracked through broker events
 - state is persisted after fills, order updates, and equity updates
 - `getStatus()` returns runtime and risk state for health checks
 
+Async/model-backed signals can use `LlmSignal` from the main package:
+
+```js
+import { LlmSignal } from "tradelab";
+
+const llm = new LlmSignal({
+  budgetMs: 2000,
+  onError: "skip",
+  async resolve(context) {
+    // Call a model or agent here.
+    return null;
+  },
+});
+
+const engine = new LiveEngine({
+  symbol: "AAPL",
+  interval: "1m",
+  broker,
+  signal: llm.signal,
+});
+```
+
+`LlmSignal` caches one decision per bar, passes a no-lookahead candle view to `resolve()`, and records decisions in `llm.log`. Use `backtestAsync()` to test the same signal before running it live.
+
 ## `LiveOrchestrator` quick start
 
 ```js
@@ -97,6 +122,32 @@ Use orchestrator when multiple systems should share one broker/account context.
 | `tradelab paper`  | Shortcut for `live` with paper broker mode   |
 | `tradelab status` | Inspect persisted live state                 |
 
+## Live dashboard
+
+Use `createDashboardServer()` to watch a running `LiveEngine` or `LiveOrchestrator` locally. The dashboard serves a static page over `node:http`, streams live events with Server-Sent Events at `/events`, and reads current state from `/state`.
+
+```js
+import { createDashboardServer } from "tradelab/live";
+
+const dashboard = createDashboardServer({ source: engine, port: 4317 });
+const url = await dashboard.start();
+console.log(`dashboard: ${url}`);
+
+// Later, during shutdown:
+await dashboard.close();
+```
+
+The page shows equity, day PnL, open position, risk state, and a recent event tail for signals, fills, position changes, equity updates, and risk halts. New browser clients receive a bounded replay of recent events so the page is useful immediately after opening.
+
+The CLI can start the same dashboard for both single-engine and config/orchestrator runs:
+
+```bash
+tradelab paper --symbol AAPL --interval 1m --mode polling --dashboard --dashboardPort 4317
+tradelab live --config ./live-portfolio.json --paper --dashboard --dashboardPort 4317
+```
+
+The dashboard implementation is ESM-first. The CommonJS live bundle can be imported, but packaged dashboard usage should prefer `import { createDashboardServer } from "tradelab/live"`.
+
 ### Single-system paper run
 
 ```bash

package/docs/mcp.md

@@ -0,0 +1,64 @@
+# MCP server
+
+<small>[Back to main page](README.md)</small>
+
+`tradelab-mcp` exposes the research loop to MCP-capable agents such as Claude Desktop, Cursor, and Claude Code.
+
+## Tools
+
+| Tool              | Purpose                                                                 |
+| ----------------- | ----------------------------------------------------------------------- |
+| `list_strategies` | List built-in strategies and their tunable parameters                   |
+| `fetch_candles`   | Fetch Yahoo or CSV candles and return a compact first/last bar summary  |
+| `run_backtest`    | Run a named strategy with JSON params and return compact metrics        |
+| `walk_forward`    | Run a named strategy over a parameter grid and return stability metrics |
+
+Tool outputs are summaries for agent context, not full report payloads. `run_backtest` returns metrics and a small trade preview, but not replay frames.
+
+## Agent research loop
+
+1. Call `list_strategies` to inspect available strategy names and parameters.
+2. Call `fetch_candles` or provide inline `candles`.
+3. Call `run_backtest` with a strategy name and params.
+4. Read `metrics`, especially trade count, profit factor, drawdown, and annualized Sharpe.
+5. Call `walk_forward` with a parameter grid to check out-of-sample stability.
+
+## Claude Desktop config
+
+Use this with the published package:
+
+```json
+{
+  "mcpServers": {
+    "tradelab": {
+      "command": "npx",
+      "args": ["-y", "tradelab", "tradelab-mcp"]
+    }
+  }
+}
+```
+
+After installing globally with `npm install -g tradelab`, you can use:
+
+```json
+{
+  "mcpServers": {
+    "tradelab": {
+      "command": "tradelab-mcp"
+    }
+  }
+}
+```
+
+## Strategies
+
+Agents cannot pass JavaScript closures over MCP, so strategies are name-addressable. Built-ins currently include:
+
+- `ema-cross`
+- `rsi-reversion`
+- `donchian-breakout`
+- `buy-hold`
+
+Register custom strategies in application code with `registerStrategy(name, def)` from the main package. A strategy definition includes `description`, `params`, and a `factory(params)` function that returns a normal tradelab `signal(context)`.
+
+<small>[Back to main page](README.md)</small>

package/docs/research.md

@@ -0,0 +1,103 @@
+# Research & overfitting
+
+<small>[Back to main page](README.md)</small>
+
+The `research` namespace contains pure statistical helpers for checking whether a backtest is robust enough to take seriously.
+
+```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,
+  sharpeStd: 0.5,
+  skew: 0,
+  kurtosis: 3,
+});
+console.log("Deflated Sharpe prob:", dsr);
+```
+
+## `research.monteCarlo(options)`
+
+Seeded block-bootstrap of trade PnLs.
+
+```js
+research.monteCarlo({
+  tradePnls,
+  equityStart: 10_000,
+  iterations: 1000,
+  blockSize: 1,
+  seed: "run-1",
+});
+```
+
+Returns:
+
+- `finalEquity`: `{ p5, p25, p50, p75, p95 }`
+- `maxDrawdown`: `{ p5, p25, p50, p75, p95 }`
+- `pathBands`: per-trade-step `{ p5, p50, p95 }` equity bands
+- `probProfit`: fraction of simulations ending above starting equity
+
+Use `blockSize > 1` when you want to preserve short streaks in the resampled trade sequence.
+
+## `research.deflatedSharpe(options)`
+
+Returns a probability in `[0, 1]` that the observed Sharpe is real after accounting for finite sample size, non-normality, and multiple trials.
+
+```js
+research.deflatedSharpe({
+  sharpe,
+  sampleSize,
+  numTrials,
+  sharpeStd,
+  skew,
+  kurtosis,
+});
+```
+
+Below roughly `0.95`, treat the Sharpe as not convincingly significant.
+
+## `research.sweepHaircut(options)`
+
+Estimates the expected maximum Sharpe under the null when trying many strategy variants.
+
+```js
+research.sweepHaircut({ numTrials: 50, sharpeStd: 0.4 });
+```
+
+Use `expectedMaxSharpe` as the multiple-testing hurdle your selected strategy should clear.
+
+## `research.probabilityOfBacktestOverfitting(matrix, options)`
+
+CSCV estimate of Probability of Backtest Overfitting.
+
+```js
+const matrix = parameterSets.map((params) => returnsForParams(params));
+const pbo = research.probabilityOfBacktestOverfitting(matrix, { groups: 8 });
+```
+
+Rows are strategy variants or parameter sets. Columns are per-period returns. `pbo > 0.5` means the selection process is likely overfit; lower is better.
+
+## `research.combinatorialPurgedSplits(options)`
+
+Creates CPCV train/test index splits with optional embargo.
+
+```js
+const splits = research.combinatorialPurgedSplits({
+  nObservations: candles.length,
+  nGroups: 6,
+  nTestGroups: 2,
+  embargo: 3,
+});
+```
+
+Each split is `{ train, test, testGroups }`. Training observations near test blocks are purged by `embargo` observations to reduce leakage from overlapping or serially correlated samples.
+
+<small>[Back to main page](README.md)</small>

package/docs/superpowers/plans/2026-00-overview.md

@@ -0,0 +1,101 @@
+# tradelab 2026 Roadmap — Overview & Sequencing
+
+> **For agentic workers:** Each subsystem below has its own plan file. Use
+> `superpowers:subagent-driven-development` (recommended) or
+> `superpowers:executing-plans` to implement one plan at a time, task-by-task.
+> All step lists use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Turn tradelab from a strong single-run backtester into an AI-native,
+statistically-defensible research + execution platform for quants, simple
+traders, and autonomous agents.
+
+---
+
+## The 8 subsystems
+
+| #   | Plan file                                                            | What it delivers                                                                                      | Depends on  |
+| --- | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ----------- |
+| 1   | [2026-01-metrics-correctness.md](2026-01-metrics-correctness.md)     | Annualized Sharpe/Sortino, finite-clamped metrics JSON, benchmark alpha/beta/IR                       | —           |
+| 2   | [2026-02-indicator-library.md](2026-02-indicator-library.md)         | `tradelab/ta` namespace: RSI, MACD, Bollinger, VWAP, Supertrend, Donchian, Keltner, stochastics       | —           |
+| 3   | [2026-03-overfitting-toolkit.md](2026-03-overfitting-toolkit.md)     | CPCV, PBO, Deflated Sharpe, Monte Carlo bands, sweep haircut                                          | 1           |
+| 4   | [2026-04-async-signals-seeding.md](2026-04-async-signals-seeding.md) | `async signal()` with per-bar budget + cache + no-lookahead guard, `LlmSignal`, configurable RNG seed | —           |
+| 5   | [2026-05-mcp-server.md](2026-05-mcp-server.md)                       | `tradelab/mcp` server exposing data/backtest/walk-forward/metrics as agent tools                      | 1, 4 (soft) |
+| 6   | [2026-06-parallel-param-sweep.md](2026-06-parallel-param-sweep.md)   | Worker-pool param sweep + `optimize()` API                                                            | —           |
+| 7   | [2026-07-funding-carry-costs.md](2026-07-funding-carry-costs.md)     | Funding/borrow/overnight carry in the cost model                                                      | —           |
+| 8   | [2026-08-live-dashboard.md](2026-08-live-dashboard.md)               | Local realtime dashboard for `LiveEngine`/`LiveOrchestrator`                                          | —           |
+
+### Dependency graph
+
+```
+1 metrics ──► 3 overfitting
+1 metrics ──► 5 mcp (soft: nicer tool output)
+4 async ────► 5 mcp (soft: agent-driven backtests)
+2, 6, 7, 8 are independent
+```
+
+### Recommended execution order
+
+1. **Plan 1 (metrics)** — small, corrects existing bugs, unblocks 3 and 5.
+2. **Plan 2 (indicators)** — independent, high user value, unblocks NL strategies later.
+3. **Plan 4 (async signals + seed)** — engine change; do before MCP so agents can drive live.
+4. **Plan 5 (MCP)** — the 2026 headline; sits on top of 1 + 4.
+5. **Plan 3 (overfitting)** — the quant moat; needs clean metrics.
+6. **Plans 6, 7, 8** — parallelizable, any order.
+
+---
+
+## Shared conventions (all plans assume these)
+
+**Runtime:** Node `>=18`, ESM (`"type": "module"`). No transpile step for `src/`.
+The CJS build is generated by `npm run build` (esbuild) from `src/`.
+
+**Tests:** `node:test` + `node:assert/strict`. Run a single file with:
+
+```bash
+node --test test/<name>.test.js
+```
+
+Run everything with `npm test` (`node --test`). New test files live under `test/`
+mirroring `src/` layout (e.g. `src/metrics/finite.js` → `test/metrics/finite.test.js`).
+There is no test runner config — discovery is by filename.
+
+**Lint/format before commit:**
+
+```bash
+npm run lint
+npm run format:check
+```
+
+**Commit style:** match existing history — `feat:`, `fix:`, `docs:`, `perf:`,
+`test:`. Every commit message MUST end with the trailer:
+
+```
+Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
+```
+
+**Public exports:** add new top-level exports in [src/index.js](../../../src/index.js).
+New subpath entrypoints (`tradelab/ta`, `tradelab/mcp`) require an entry in the
+`exports` map of [package.json](../../../package.json) AND a matching CJS bundle
+in [scripts/build-cjs.mjs](../../../scripts/build-cjs.mjs).
+
+**Canonical result shape (do not break it):** every engine returns
+`{ symbol, interval, range, trades, positions, openPositions, metrics, eqSeries, replay }`.
+`buildMetrics` is the single source of truth for `metrics`. Plans that add metrics
+fields ADD keys; they never rename or remove existing ones (dashboards depend on them).
+
+**The signal contract (do not break it):** `signal(context)` receives
+`{ candles, index, bar, equity, openPosition, pendingOrder }` and returns `null`
+or `{ side, entry?, stop, rr|takeProfit, ... }`. Two engines call it independently:
+the standalone loop in [src/engine/backtest.js](../../../src/engine/backtest.js) and
+the shared [src/engine/barSystemRunner.js](../../../src/engine/barSystemRunner.js)
+(used by portfolio). The live path uses
+[src/live/engine/liveEngine.js](../../../src/live/engine/liveEngine.js). Plan 4
+touches all three call sites.
+
+---
+
+## Out of scope for this roadmap
+
+- Natural-language → signal compiler (separate spec; depends on Plan 2 + a strategy schema).
+- New broker adapters / options / fundamentals data sources.
+- L2 microstructure simulator.