tradelab 0.3.0 → 0.5.0

package/src/engine/portfolio.js

@@ -1,57 +1,35 @@
 import { buildMetrics } from "../metrics/buildMetrics.js";
-import { backtest } from "./backtest.js";
-import { estimateBarMs } from "./execution.js";
+import { estimateBarMs, dayKeyET } from "./execution.js";
+import { BarSystemRunner, defaultSystemCap } from "./barSystemRunner.js";
 
 function asWeight(value) {
   return Number.isFinite(value) && value > 0 ? value : 0;
 }
 
-function combineEquitySeries(systemRuns, totalEquity) {
-  const timeline = new Set();
-  for (const run of systemRuns) {
-    for (const point of run.result.eqSeries || []) {
-      timeline.add(point.time);
-    }
-  }
-
-  const times = [...timeline].sort((left, right) => left - right);
-  if (!times.length) {
-    return [{ time: 0, timestamp: 0, equity: totalEquity }];
-  }
-
-  const states = systemRuns.map((run) => ({
-    points: run.result.eqSeries || [],
-    index: 0,
-    lastEquity: run.allocationEquity,
-  }));
-
-  return times.map((time) => {
-    let equity = 0;
-    states.forEach((state) => {
-      while (
-        state.index < state.points.length &&
-        state.points[state.index].time <= time
-      ) {
-        state.lastEquity = state.points[state.index].equity;
-        state.index += 1;
-      }
-      equity += state.lastEquity;
-    });
+function buildPortfolioPoint(time, equity, lockedCapital, availableCapital) {
+  return {
+    time,
+    timestamp: time,
+    equity,
+    lockedCapital,
+    availableCapital,
+  };
+}
 
-    return { time, timestamp: time, equity };
-  });
+function stableSystemOrder(left, right) {
+  return left.index - right.index;
 }
 
-function combineReplay(systemRuns, eqSeries, collectReplay) {
+function combineReplay(systemResults, eqSeries, collectReplay) {
   if (!collectReplay) {
     return { frames: [], events: [] };
   }
 
-  const events = systemRuns
-    .flatMap((run) =>
-      (run.result.replay?.events || []).map((event) => ({
+  const events = systemResults
+    .flatMap((entry) =>
+      (entry.result.replay?.events || []).map((event) => ({
         ...event,
-        symbol: event.symbol || run.symbol,
+        symbol: event.symbol || entry.symbol,
       }))
     )
     .sort((left, right) => new Date(left.t).getTime() - new Date(right.t).getTime());
@@ -62,17 +40,82 @@ function combineReplay(systemRuns, eqSeries, collectReplay) {
     equity: point.equity,
     posSide: null,
     posSize: 0,
+    lockedCapital: point.lockedCapital,
+    availableCapital: point.availableCapital,
   }));
 
   return { frames, events };
 }
 
+function portfolioState(runners, initialEquity) {
+  let markedEquity = initialEquity;
+  let lockedCapital = 0;
+
+  for (const { runner, initialReferenceEquity } of runners) {
+    markedEquity += runner.getMarkedEquity() - initialReferenceEquity;
+    lockedCapital += runner.getLockedCapital();
+  }
+
+  return {
+    markedEquity,
+    lockedCapital,
+    availableCapital: markedEquity - lockedCapital,
+  };
+}
+
+function findNextTimeAndActive(runners) {
+  let nextTime = Infinity;
+  const active = [];
+
+  for (const entry of runners) {
+    const time = entry.runner.peekTime();
+    if (time < nextTime) {
+      nextTime = time;
+      active.length = 0;
+      active.push(entry);
+      continue;
+    }
+    if (time === nextTime) {
+      active.push(entry);
+    }
+  }
+
+  return { nextTime, active };
+}
+
+function initialPortfolioTime(runners) {
+  let time = Infinity;
+  for (const { runner } of runners) {
+    const next = runner.candles[0]?.time ?? Infinity;
+    if (next < time) time = next;
+  }
+  return Number.isFinite(time) ? time : 0;
+}
+
+function resolveSystemCap(systemEntry, totalEquity) {
+  return defaultSystemCap(
+    Math.max(0, totalEquity),
+    systemEntry.defaultCapPct,
+    systemEntry.system.maxAllocation,
+    systemEntry.system.maxAllocationPct
+  );
+}
+
+function forceExitAll(runners, time) {
+  for (const { runner } of runners) {
+    if (!runner.open) continue;
+    const price = runner.getMarkPrice();
+    if (!Number.isFinite(price)) continue;
+    runner.forceExit("PORTFOLIO_DAILY_LOSS", { time, close: price }, price);
+  }
+}
+
 /**
- * Run multiple symbol/system backtests and aggregate them into a portfolio view.
+ * Run multiple systems against a shared capital pool.
  *
- * Capital is allocated up front per system using weights. Each system then runs
- * through the normal single-symbol backtest engine and the portfolio result
- * aggregates trades, positions, equity, replay events, and metrics.
+ * Existing allocation weights are preserved as default per-system capital caps,
+ * but capital is only locked when a fill actually occurs. Systems therefore
+ * compete for the same remaining capital at fill time.
  */
 export function backtestPortfolio({
   systems = [],
@@ -80,6 +123,7 @@ export function backtestPortfolio({
   allocation = "equal",
   collectEqSeries = true,
   collectReplay = false,
+  maxDailyLossPct = 0,
 } = {}) {
   if (!Array.isArray(systems) || systems.length === 0) {
     throw new Error("backtestPortfolio() requires a non-empty systems array");
@@ -89,30 +133,115 @@ export function backtestPortfolio({
     allocation === "equal"
       ? systems.map(() => 1)
       : systems.map((system) => asWeight(system.weight || 0));
-  const totalWeight = weights.reduce((sum, weight) => sum + weight, 0);
+  const totalWeight = weights.reduce((sumValue, weight) => sumValue + weight, 0);
 
   if (!(totalWeight > 0)) {
     throw new Error("backtestPortfolio() requires positive allocation weights");
   }
 
-  const systemRuns = systems.map((system, index) => {
-    const allocationEquity = equity * (weights[index] / totalWeight);
-    const result = backtest({
-      ...system,
-      equity: allocationEquity,
-      collectEqSeries,
-      collectReplay,
-    });
-
+  const runners = systems.map((system, index) => {
+    const defaultCapPct = weights[index] / totalWeight;
+    const initialReferenceEquity = equity * defaultCapPct;
     return {
-      symbol: system.symbol ?? result.symbol ?? `system-${index + 1}`,
-      weight: weights[index],
-      allocationEquity,
-      result,
+      index,
+      symbol: system.symbol ?? `system-${index + 1}`,
+      system,
+      defaultCapPct,
+      initialReferenceEquity,
+      runner: new BarSystemRunner({
+        ...system,
+        symbol: system.symbol ?? `system-${index + 1}`,
+        equity: initialReferenceEquity,
+        collectEqSeries,
+        collectReplay,
+      }),
     };
   });
 
-  const trades = systemRuns
+  const eqSeries = collectEqSeries ? [] : [];
+  let state = portfolioState(runners, equity);
+  if (collectEqSeries) {
+    eqSeries.push(
+      buildPortfolioPoint(
+        initialPortfolioTime(runners),
+        state.markedEquity,
+        state.lockedCapital,
+        state.availableCapital
+      )
+    );
+  }
+
+  let currentDay = null;
+  let dayStartEquity = equity;
+  let portfolioHalted = false;
+
+  while (true) {
+    const { nextTime, active } = findNextTimeAndActive(runners);
+    if (!Number.isFinite(nextTime)) break;
+    active.sort(stableSystemOrder);
+
+    const dayKey = dayKeyET(nextTime);
+    if (currentDay === null || dayKey !== currentDay) {
+      currentDay = dayKey;
+      state = portfolioState(runners, equity);
+      dayStartEquity = state.markedEquity;
+      portfolioHalted = false;
+    }
+
+    for (const systemEntry of active) {
+      state = portfolioState(runners, equity);
+      const totalEquity = state.markedEquity;
+      const availableCapital = Math.max(0, state.availableCapital);
+      const systemLocked = systemEntry.runner.getLockedCapital();
+      const systemCap = resolveSystemCap(systemEntry, totalEquity);
+      const systemRemainingCapital = Math.max(0, systemCap - systemLocked);
+
+      systemEntry.runner.step({
+        signalEquity: totalEquity,
+        canTrade: !portfolioHalted,
+        resolveEntrySize({ desiredSize, entryPrice }) {
+          const maxLeverage = Math.max(1, systemEntry.runner.options.maxLeverage || 1);
+          const byAvailable = (availableCapital * maxLeverage) / Math.max(1e-12, Math.abs(entryPrice));
+          const bySystemCap = (systemRemainingCapital * maxLeverage) / Math.max(1e-12, Math.abs(entryPrice));
+          return Math.min(desiredSize, byAvailable, bySystemCap);
+        },
+      });
+
+      state = portfolioState(runners, equity);
+      if (
+        !portfolioHalted &&
+        maxDailyLossPct > 0 &&
+        state.markedEquity <= dayStartEquity * (1 - Math.abs(maxDailyLossPct) / 100)
+      ) {
+        portfolioHalted = true;
+        for (const { runner } of runners) runner.cancelPending();
+        forceExitAll(runners, nextTime);
+        state = portfolioState(runners, equity);
+      }
+    }
+
+    if (collectEqSeries) {
+      eqSeries.push(
+        buildPortfolioPoint(
+          nextTime,
+          state.markedEquity,
+          state.lockedCapital,
+          state.availableCapital
+        )
+      );
+    }
+  }
+
+  const systemResults = runners.map((entry) => ({
+    symbol: entry.symbol,
+    weight: entry.defaultCapPct,
+    equity: entry.initialReferenceEquity,
+    allocationCapPct: entry.defaultCapPct,
+    allocationCap: resolveSystemCap(entry, equity),
+    result: entry.runner.buildResult(),
+  }));
+
+  const trades = systemResults
     .flatMap((run) =>
       run.result.trades.map((trade) => ({
         ...trade,
@@ -120,7 +249,7 @@ export function backtestPortfolio({
       }))
     )
     .sort((left, right) => left.exit.time - right.exit.time);
-  const positions = systemRuns
+  const positions = systemResults
     .flatMap((run) =>
       run.result.positions.map((trade) => ({
         ...trade,
@@ -128,8 +257,7 @@ export function backtestPortfolio({
       }))
     )
     .sort((left, right) => left.exit.time - right.exit.time);
-  const eqSeries = collectEqSeries ? combineEquitySeries(systemRuns, equity) : [];
-  const replay = combineReplay(systemRuns, eqSeries, collectReplay);
+  const replay = combineReplay(systemResults, eqSeries, collectReplay);
   const allCandles = systems.flatMap((system) => system.candles || []);
   const orderedCandles = [...allCandles].sort((left, right) => left.time - right.time);
   const metrics = buildMetrics({
@@ -150,11 +278,6 @@ export function backtestPortfolio({
     metrics,
     eqSeries,
     replay,
-    systems: systemRuns.map((run) => ({
-      symbol: run.symbol,
-      weight: run.weight / totalWeight,
-      equity: run.allocationEquity,
-      result: run.result,
-    })),
+    systems: systemResults,
   };
 }

package/src/engine/walkForward.js

@@ -19,6 +19,73 @@ function stitchEquitySeries(target, source) {
   target.push(...nextPoints);
 }
 
+function canonicalParams(params) {
+  const entries = Object.entries(params || {}).sort(([left], [right]) =>
+    left.localeCompare(right)
+  );
+  return JSON.stringify(Object.fromEntries(entries));
+}
+
+function buildWindowRanges(length, trainBars, testBars, stepBars, mode) {
+  const ranges = [];
+  for (
+    let start = 0;
+    start + trainBars + testBars <= length;
+    start += stepBars
+  ) {
+    const trainStart = mode === "anchored" ? 0 : start;
+    const trainEnd = mode === "anchored" ? trainBars + start : start + trainBars;
+    const testStart = trainEnd;
+    const testEnd = testStart + testBars;
+    if (testEnd > length) break;
+    ranges.push({ trainStart, trainEnd, testStart, testEnd });
+  }
+  return ranges;
+}
+
+function summarizeBestParams(windows) {
+  const summaryBySignature = new Map();
+  let adjacentRepeats = 0;
+
+  windows.forEach((window, index) => {
+    const signature = window.bestParamsSignature ?? canonicalParams(window.bestParams);
+    const current = summaryBySignature.get(signature) || {
+      params: window.bestParams,
+      wins: 0,
+      profitableWindows: 0,
+      oosTrades: 0,
+    };
+    current.wins += 1;
+    current.profitableWindows += window.profitable ? 1 : 0;
+    current.oosTrades += window.oosTrades;
+    summaryBySignature.set(signature, current);
+
+    if (
+      index > 0 &&
+      (windows[index - 1].bestParamsSignature ??
+        canonicalParams(windows[index - 1].bestParams)) === signature
+    ) {
+      adjacentRepeats += 1;
+    }
+  });
+
+  const byFrequency = [...summaryBySignature.values()].sort((left, right) => {
+    if (right.wins !== left.wins) return right.wins - left.wins;
+    return right.profitableWindows - left.profitableWindows;
+  });
+  const adjacentPairs = Math.max(0, windows.length - 1);
+
+  return {
+    winners: windows.map((window) => window.bestParams),
+    stability: {
+      adjacentRepeatRate: adjacentPairs ? adjacentRepeats / adjacentPairs : 0,
+      uniqueWinnerCount: summaryBySignature.size,
+      dominant: byFrequency[0] || null,
+      leaderboard: byFrequency,
+    },
+  };
+}
+
 /**
  * Run rolling walk-forward optimization over a single candle series.
  *
@@ -32,6 +99,7 @@ export function walkForwardOptimize({
   trainBars,
   testBars,
   stepBars = testBars,
+  mode = "rolling",
   scoreBy = "profitFactor",
   backtestOptions = {},
 } = {}) {
@@ -47,25 +115,31 @@ export function walkForwardOptimize({
   if (!(trainBars > 0) || !(testBars > 0) || !(stepBars > 0)) {
     throw new Error("walkForwardOptimize() requires positive trainBars, testBars, and stepBars");
   }
+  if (mode !== "rolling" && mode !== "anchored") {
+    throw new Error('walkForwardOptimize() mode must be "rolling" or "anchored"');
+  }
 
   const windows = [];
   const allTrades = [];
   const allPositions = [];
   const eqSeries = [];
   let rollingEquity = backtestOptions.equity ?? 10_000;
+  const ranges = buildWindowRanges(candles.length, trainBars, testBars, stepBars, mode);
+  const trainBacktestOptions = {
+    ...backtestOptions,
+    collectEqSeries: false,
+    collectReplay: false,
+  };
+  const testBacktestOptions = { ...backtestOptions };
 
-  for (
-    let start = 0;
-    start + trainBars + testBars <= candles.length;
-    start += stepBars
-  ) {
-    const trainSlice = candles.slice(start, start + trainBars);
-    const testSlice = candles.slice(start + trainBars, start + trainBars + testBars);
+  for (const range of ranges) {
+    const trainSlice = candles.slice(range.trainStart, range.trainEnd);
+    const testSlice = candles.slice(range.testStart, range.testEnd);
 
     let best = null;
     for (const params of parameterSets) {
       const trainResult = backtest({
-        ...backtestOptions,
+        ...trainBacktestOptions,
         candles: trainSlice,
         equity: rollingEquity,
         signal: signalFactory(params),
@@ -77,11 +151,12 @@ export function walkForwardOptimize({
     }
 
     const testResult = backtest({
-      ...backtestOptions,
+      ...testBacktestOptions,
       candles: testSlice,
       equity: rollingEquity,
       signal: signalFactory(best.params),
     });
+    const bestParamsSignature = canonicalParams(best.params);
 
     rollingEquity = testResult.metrics.finalEquity;
     allTrades.push(...testResult.trades);
@@ -101,10 +176,29 @@ export function walkForwardOptimize({
       trainScore: best.score,
       trainMetrics: best.metrics,
       testMetrics: testResult.metrics,
+      oosTrades: testResult.metrics.trades,
+      profitable: testResult.metrics.totalPnL > 0,
+      stabilityScore: 0,
+      bestParamsSignature,
       result: testResult,
     });
   }
 
+  for (let index = 0; index < windows.length; index += 1) {
+    const currentSignature = windows[index].bestParamsSignature;
+    const adjacent = [];
+    if (index > 0) {
+      adjacent.push(windows[index - 1].bestParamsSignature === currentSignature ? 1 : 0);
+    }
+    if (index + 1 < windows.length) {
+      adjacent.push(windows[index + 1].bestParamsSignature === currentSignature ? 1 : 0);
+    }
+    windows[index].stabilityScore = adjacent.length
+      ? adjacent.reduce((total, value) => total + value, 0) / adjacent.length
+      : 1;
+    delete windows[index].bestParamsSignature;
+  }
+
   const metrics = buildMetrics({
     closed: allTrades,
     equityStart: backtestOptions.equity ?? 10_000,
@@ -113,6 +207,7 @@ export function walkForwardOptimize({
     estBarMs: estimateBarMs(candles),
     eqSeries,
   });
+  const bestParamsSummary = summarizeBestParams(windows);
 
   return {
     windows,
@@ -121,6 +216,7 @@ export function walkForwardOptimize({
     metrics,
     eqSeries,
     replay: { frames: [], events: [] },
-    bestParams: windows.map((window) => window.bestParams),
+    bestParams: Object.assign(windows.map((window) => window.bestParams), bestParamsSummary),
+    bestParamsSummary: bestParamsSummary.stability,
   };
 }

package/src/index.js

@@ -1,4 +1,5 @@
 export { backtest } from "./engine/backtest.js";
+export { backtestTicks } from "./engine/backtestTicks.js";
 export { backtestPortfolio } from "./engine/portfolio.js";
 export { walkForwardOptimize } from "./engine/walkForward.js";