tradelab 1.0.1 → 1.2.0

package/docs/backtest-engine.md

@@ -1,38 +1,28 @@
-# Backtest engine
+# Backtesting
 
-<small>[Back to main page](README.md)</small>
+This guide covers the research engine: `backtest`, `backtestAsync`, `backtestTicks`, `backtestPortfolio`, `walkForwardOptimize`, `optimize`, and `buildMetrics`.
 
-This page covers the simulation layer:
+[Back to docs](README.md)
 
-- `backtest(options)`
-- `backtestTicks(options)`
-- `backtestPortfolio(options)`
-- `walkForwardOptimize(options)`
-- `buildMetrics(input)`
+## Choose an Entry Point
 
-## Overview
+| Use this when...                        | Call                           |
+| --------------------------------------- | ------------------------------ |
+| You have candles for one symbol         | `backtest(options)`            |
+| Your signal returns a promise           | `backtestAsync(options)`       |
+| You have tick or quote data             | `backtestTicks(options)`       |
+| You want one result across many systems | `backtestPortfolio(options)`   |
+| You want rolling train/test validation  | `walkForwardOptimize(options)` |
+| You want a worker-pool parameter sweep  | `optimize(options)`            |
+| You already have trades and equity data | `buildMetrics(input)`          |
 
-Use the engine layer when you already have candles and want to simulate strategy behavior, inspect the result, and export or post-process it.
+## Candle Shape
 
-The same `signal()` contract is used by `LiveEngine` in `tradelab/live`, so strategy logic can move from research to execution without rewriting signal inputs.
-
-## Choose the right function
-
-| Use case                                  | Function                |
-| ----------------------------------------- | ----------------------- |
-| One strategy on one candle series         | `backtest()`            |
-| One strategy on tick or quote data        | `backtestTicks()`       |
-| Multiple symbols with one combined result | `backtestPortfolio()`   |
-| Rolling or anchored train/test validation | `walkForwardOptimize()` |
-| Recompute metrics from realized trades    | `buildMetrics()`        |
-
-## Candle input
-
-Candles should be sorted in ascending time order.
+Candles should be sorted oldest to newest.
 
 ```js
 {
-  time: 1735828200000,
+  time: 1735828200000, // Unix milliseconds
   open: 100,
   high: 102,
   low: 99,
@@ -41,117 +31,116 @@ Candles should be sorted in ascending time order.
 }
 ```
 
-The package also normalizes common aliases such as `timestamp`, `date`, `o`, `h`, `l`, and `c`.
-
-## `backtest(options)`
-
-`backtest()` is the main single-symbol entry point.
+The data loaders normalize common aliases such as `timestamp`, `date`, `o`, `h`, `l`, and `c`.
 
-### Minimal example
+## First Backtest
 
 ```js
 import { backtest } from "tradelab";
 
 const result = backtest({
   candles,
-  signal({ bar, index }) {
-    if (index !== 20) return null;
+  symbol: "SPY",
+  interval: "1d",
+  equity: 10_000,
+  riskPct: 1,
+  warmupBars: 50,
+  signal({ bar, index, openPosition }) {
+    if (openPosition || index < 50) return null;
     return {
       side: "long",
-      entry: bar.close,
-      stop: bar.close - 2,
+      stop: bar.close * 0.97,
       rr: 2,
     };
   },
 });
-```
-
-### Required fields
 
-```js
-{
-  candles: Candle[],
-  signal: ({ candles, index, bar, equity, openPosition, pendingOrder }) => Signal | null
-}
+console.log(result.metrics);
 ```
 
-### Core options
+Set these options first:
 
-| Option                             | Purpose                                                        |
-| ---------------------------------- | -------------------------------------------------------------- |
-| `symbol`, `interval`, `range`      | Labels carried into results and exports                        |
-| `equity`                           | Starting equity, default `10000`                               |
-| `riskPct` or `riskFraction`        | Default risk per trade when `qty` is not provided              |
-| `warmupBars`                       | Bars skipped before signal evaluation starts                   |
-| `flattenAtClose`                   | Forces end-of-day exit when enabled                            |
-| `collectEqSeries`, `collectReplay` | Builds extra output for charts and exports                     |
-| `strict`                           | Throws on direct lookahead access such as `candles[index + 1]` |
-| `costs`                            | Slippage, spread, and commission model                         |
+| Option       | Why it matters                                |
+| ------------ | --------------------------------------------- |
+| `symbol`     | Labels results and exports                    |
+| `interval`   | Annualizes metrics correctly                  |
+| `equity`     | Starting account value                        |
+| `riskPct`    | Default risk per trade when `qty` is absent   |
+| `warmupBars` | Prevents indicators from trading before ready |
+| `costs`      | Keeps edge estimates from ignoring friction   |
 
-If you are starting from scratch, the most useful options to set explicitly are:
+## Signal Contract
 
-- `equity`
-- `riskPct`
-- `warmupBars`
-- `flattenAtClose`
-- `costs`
+Every engine calls your strategy with the same shape:
 
-### Signal contract
+```js
+signal({ candles, index, bar, equity, openPosition, pendingOrder });
+```
 
-The signal function receives a context object with these fields:
+Return `null` to skip the bar. Return a signal object to enter.
 
-<!-- prettier-ignore -->
 ```js
-{ candles, index, bar, equity, openPosition, pendingOrder }
+{
+  side: "long",
+  entry: 101.25,
+  stop: 99.75,
+  takeProfit: 104.25
+}
 ```
 
-Return `null` for no trade, or a signal object:
+You can omit `entry`; the engine uses the current close. You can also omit `takeProfit` when you provide `rr`.
 
 ```js
-// minimal
-{ side: "long", stop: 99.75, rr: 2 }
-
-// explicit targets
-{ side: "long", entry: 101.25, stop: 99.75, takeProfit: 104.25 }
+{ side: "short", stop: 105, rr: 2 }
 ```
 
-### Signal conveniences
-
-| Field                       | Behavior                                         |
-| --------------------------- | ------------------------------------------------ |
-| `side`                      | Accepts `long`, `short`, `buy`, or `sell`        |
-| `entry`                     | Defaults to the current close if omitted         |
-| `takeProfit`                | Can be derived from `rr` or `_rr`                |
-| `qty` or `size`             | Overrides risk-based sizing                      |
-| `riskPct` or `riskFraction` | Overrides the global risk setting for that trade |
+Useful signal fields:
 
-Practical rule: return the smallest signal object that expresses the trade clearly. In many strategies that is just `side`, `stop`, and `rr`.
+| Field                        | Meaning                           |
+| ---------------------------- | --------------------------------- |
+| `side`                       | `long`, `short`, `buy`, or `sell` |
+| `entry`, `limit`, `price`    | Entry price aliases               |
+| `stop`, `stopLoss`, `sl`     | Stop price aliases                |
+| `takeProfit`, `target`, `tp` | Target price aliases              |
+| `rr` or `_rr`                | Target in R multiples             |
+| `qty` or `size`              | Fixed position size               |
+| `riskPct` or `riskFraction`  | Per-trade risk override           |
 
-### Optional per-trade hints
+## Async Signals
 
-These values are read from the signal object when present:
+Use `backtestAsync()` when your signal waits on a model, service, file read, or other async work.
 
-- `_entryExpiryBars`
-- `_cooldownBars`
-- `_breakevenAtR`
-- `_trailAfterR`
-- `_maxBarsInTrade`
-- `_maxHoldMin`
-- `_rr`
-- `_initRisk`
-- `_imb`
+```js
+import { backtestAsync, LlmSignal } from "tradelab";
+
+const modelSignal = new LlmSignal({
+  budgetMs: 2000,
+  onError: "skip",
+  async resolve({ candles, bar }) {
+    const recent = candles.slice(-10);
+    return recent.at(-1).close > recent[0].close
+      ? { side: "long", stop: bar.close * 0.98, rr: 2 }
+      : null;
+  },
+});
 
-### Execution and cost model
+const result = await backtestAsync({
+  candles,
+  signal: modelSignal.signal,
+  signalBudgetMs: 3000,
+});
+```
 
-Legacy options still work:
+`LlmSignal` caches one decision per bar, blocks lookahead access, records decisions in `log`, and can either skip or throw on errors.
 
-- `slippageBps`
-- `feeBps`
+## Costs
 
-For more control, use `costs`:
+The old top-level `slippageBps` and `feeBps` options still work. Prefer `costs` for new work:
 
 ```js
-{
+const result = backtest({
+  candles,
+  signal,
   costs: {
     slippageBps: 2,
     spreadBps: 1,
@@ -161,217 +150,186 @@ For more control, use `costs`:
       stop: 4,
     },
     commissionBps: 1,
-    commissionPerUnit: 0,
     commissionPerOrder: 1,
     minCommission: 1,
+    carry: {
+      longAnnualBps: 500,
+      shortAnnualBps: 800,
+    },
+    funding: {
+      rateBps: 10,
+      intervalMs: 8 * 60 * 60 * 1000,
+      anchorMs: 0,
+    },
   },
-}
+});
 ```
 
-### Cost model behavior
-
-- slippage is applied in trade direction
-- 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
-
-This is still a bar-based simulation. It does not model queue position, exchange microstructure, or realistic intrabar order priority.
+How the cost model works:
 
-### Advanced trade management
+- slippage is applied in the trade direction
+- spread is paid as half-spread on entry and exit
+- commission can be bps-based, per-unit, per-order, or mixed
+- `minCommission` applies per fill
+- carry is annualized and deducted when a leg closes
+- funding applies at boundaries in `(openTime, closeTime]`
+- positive funding charges longs and credits shorts
 
-These are optional. Ignore them until the strategy actually needs them.
+Closed trades include `exit.financing` when carry or funding applies. It is already included in `exit.pnl`.
 
-- `scaleOutAtR`, `scaleOutFrac`, `finalTP_R`
-- `maxDailyLossPct`, `dailyMaxTrades`, `postLossCooldownBars`
-- `atrTrailMult`, `atrTrailPeriod`
-- `mfeTrail`
-- `pyramiding`
-- `volScale`
-- `entryChase`
-- `qtyStep`, `minQty`, `maxLeverage`
-- `reanchorStopOnFill`, `maxSlipROnFill`
-- `oco`
-- `triggerMode`
+## Result Shape
 
-Recommended order of adoption:
-
-1. Start with `entry`, `stop`, and `rr`
-2. Add `costs`
-3. Add trailing, scale-outs, or pyramiding only if the real strategy uses them
-
-## Result shape
-
-`backtest()` returns an object with these fields:
-
-<!-- prettier-ignore -->
 ```js
-{ symbol, interval, range, trades, positions, openPositions, metrics, eqSeries, replay }
+{
+  (symbol,
+    interval,
+    range,
+    trades, // every realized leg
+    positions, // completed positions
+    openPositions, // still open at the end
+    metrics,
+    eqSeries,
+    replay);
+}
 ```
 
-### `trades`
-
-Every realized leg, including partial exits and scale-outs.
-
-### `positions`
-
-Completed positions only. This is the collection most users want for top-line analysis.
-
-If you are unsure whether to use `trades` or `positions`, start with `positions`.
-
-### `metrics`
+Use `positions` for normal trade analysis. Use `trades` when you need partial exits or scale-out legs.
 
-Most users start with:
+Important metrics:
 
-- `trades`
-- `winRate`
-- `expectancy`
-- `profitFactor`
-- `maxDrawdown`
-- `sharpe`
-- `avgHold`
-- `returnPct`
-- `totalPnL`
-- `finalEquity`
-- `sideBreakdown`
+| Metric                 | Meaning                                                                             |
+| ---------------------- | ----------------------------------------------------------------------------------- |
+| `trades`               | Number of completed positions                                                       |
+| `winRate`              | Winning completed positions / all positions                                         |
+| `profitFactor`         | Gross profit / gross loss                                                           |
+| `totalPnL`             | Realized PnL                                                                        |
+| `returnPct`            | Return on starting equity                                                           |
+| `maxDrawdown`          | Max drawdown as a decimal                                                           |
+| `sharpeDaily`          | Daily-bucketed Sharpe                                                               |
+| `sharpeAnnualized`     | Annualized Sharpe                                                                   |
+| `annualizationPeriods` | Periods used for annualization                                                      |
+| `sideBreakdown`        | Long and short side summaries                                                       |
+| `benchmark`            | Alpha, beta, correlation, and information ratio when benchmark returns are supplied |
 
-Also included:
+Ratios are clamped to finite numbers before returning, so exported JSON does not contain `Infinity` or `NaN`.
 
-- position-vs-leg variants such as `profitFactor_pos` and `profitFactor_leg`
-- `rDist` percentiles
-- `holdDistMin` percentiles
-- daily stats under `daily`
+## Tick Backtests
 
-Useful first checks after any run:
-
-- `metrics.trades`: enough sample size to care
-- `metrics.profitFactor`: whether winners beat losers gross of the chosen fill model
-- `metrics.maxDrawdown`: whether the path is survivable
-- `metrics.sideBreakdown`: whether one side carries the result
-
-### `eqSeries`
-
-Realized equity points:
+`backtestTicks()` uses event-style tick or quote rows:
 
 ```js
-[{ time, timestamp, equity }];
+const result = backtestTicks({
+  ticks,
+  symbol: "BTC-USD",
+  signal,
+  queueFillProbability: 0.4,
+  seed: "btc-run-1",
+});
 ```
 
-`time` and `timestamp` contain the same Unix-millisecond value.
-
-### `replay`
-
-Visualization payload:
-
-```js
-{
-  frames: [{ t, price, equity, posSide, posSize }],
-  events: [{ t, price, type, side, size, tradeId, reason, pnl }]
-}
-```
+Supported tick fields include `time`, `price`, `last`, `bid`, `ask`, `high`, `low`, `size`, and `volume`. Market entries fill on the next tick. Limit orders can fill at touch based on `queueFillProbability`. Stops use the stop-specific slippage model when provided.
 
-This is meant for charts and reports, not as a full audit log.
+Use `seed` to make probabilistic queue fills reproducible.
 
-## `backtestPortfolio(options)`
+## Portfolio Backtests
 
-Use portfolio mode when you already have one candle array per symbol and want one combined result.
+`backtestPortfolio()` runs multiple systems against one shared account.
 
 ```js
 const result = backtestPortfolio({
   equity: 100_000,
+  interval: "1d",
+  maxDailyLossPct: 3,
   systems: [
-    { symbol: "SPY", candles: spy, signal: signalA, weight: 2 },
-    { symbol: "QQQ", candles: qqq, signal: signalB, weight: 1 },
+    { symbol: "SPY", candles: spy, signal: spySignal, weight: 2 },
+    { symbol: "QQQ", candles: qqq, signal: qqqSignal, weight: 1 },
   ],
 });
 ```
 
-### How it works
-
-- systems share one live capital pool
-- `weight` or `allocation: "equal" | "weight"` defines the default per-system cap, not a pre-funded sleeve
-- fills lock capital immediately, later fills size against remaining available capital
-- `eqSeries` points include `lockedCapital` and `availableCapital`
-- `maxDailyLossPct` can halt all systems for the rest of the day once breached
-
-### What it is not
-
-- a cross-margin broker simulator
-- a prime-broker margin model
-- a full portfolio optimizer
-
-This mode now does enforce shared capital and cross-system sizing, but it still uses the library's research-oriented execution assumptions rather than full broker accounting.
-
-## `backtestTicks(options)`
-
-Use tick mode when you want event-driven fills while keeping the same result shape as `backtest()`.
-
-```js
-const result = backtestTicks({
-  ticks,
-  queueFillProbability: 0.5,
-  signal,
-});
-```
+Weights are default allocation caps, not pre-funded sleeves. Capital is locked when a fill happens, and later fills size against what remains available.
 
-### How it works
+Portfolio result extras:
 
-- market entries fill on the next tick
-- limit orders can fill at the touch based on `queueFillProbability`
-- 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`
+- `systems`: per-system backtest results
+- `eqSeries[].lockedCapital`
+- `eqSeries[].availableCapital`
+- portfolio-level `metrics`
 
-## `walkForwardOptimize(options)`
+## Walk-Forward Validation
 
-Use walk-forward mode when one in-sample backtest is not enough and you want rolling or anchored train/test validation.
+Use `walkForwardOptimize()` to reduce the risk of choosing parameters that only worked in-sample.
 
 ```js
 const wf = walkForwardOptimize({
   candles,
-  mode: "anchored",
   trainBars: 180,
   testBars: 60,
   stepBars: 60,
+  mode: "anchored",
   scoreBy: "profitFactor",
-  parameterSets: [
-    { fast: 8, slow: 21, rr: 2 },
-    { fast: 10, slow: 30, rr: 2 },
-  ],
+  parameterSets,
   signalFactory(params) {
-    return createSignalFromParams(params);
+    return createSignal(params);
   },
 });
 ```
 
-### How it works
+For each window, tradelab:
+
+1. scores every parameter set on the training slice
+2. chooses the winner
+3. runs that winner on the test slice
+4. reports aggregate metrics and winner stability
+
+Read `wf.windows` before trusting `wf.metrics`. A strategy that changes winners every window is less convincing than one with stable winners.
+
+## Parallel Parameter Sweeps
 
-1. Evaluate every parameter set on the training slice
-2. Pick the best one by `scoreBy`
-3. Run that parameter set on the next test slice
-4. Repeat for each window using either rolling or anchored training windows
+`optimize()` runs independent parameter sets in worker threads.
 
-### Return value
+```js
+import { optimize, grid } from "tradelab";
 
-- `windows`: per-window summaries and chosen parameters
-- `trades`, `positions`, `metrics`, `eqSeries`
-- `bestParams`: chosen parameters for each window plus a stability summary
-- `bestParamsSummary`: adjacent repeat rate, dominant winner, and winner leaderboard
+const out = await optimize({
+  candles,
+  interval: "1d",
+  signalModulePath: new URL("../strategies/ema.js", import.meta.url).pathname,
+  parameterSets: grid({
+    fast: [8, 10, 12],
+    slow: [30, 50],
+  }),
+  concurrency: 4,
+  scoreBy: "sharpeAnnualized",
+});
+```
 
-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.
+The strategy module should export `createSignal(params)`.
 
-## `buildMetrics(input)`
+```js
+export function createSignal(params) {
+  return function signal(context) {
+    // return null or a trade signal
+  };
+}
+```
 
-Most users do not need this directly. Use it when:
+Functions cannot cross worker boundaries, so the worker receives a module path plus JSON-like parameter objects.
 
-- you generate realized trades outside `backtest()`
-- you filter a result and want fresh metrics
-- you combine results manually
+## Recomputing Metrics
 
-## Common mistakes
+Use `buildMetrics()` if you have realized trades and an equity curve from another process.
 
-- using unsorted candles or mixed intervals in one series
-- reading `trades` as if they were always full positions
-- leaving costs at zero and overestimating edge
-- trusting one backtest without out-of-sample validation
-- debugging a strategy with `strict: false` when lookahead is possible
+```js
+const metrics = buildMetrics({
+  closed: trades,
+  equityStart: 10_000,
+  equityFinal: 11_250,
+  candles,
+  estBarMs: 86_400_000,
+  eqSeries,
+  interval: "1d",
+});
+```
 
-<small>[Back to main page](README.md)</small>
+[Back to docs](README.md)