tradelab 0.4.0 → 1.0.0

package/src/engine/execution.js

@@ -17,20 +17,10 @@ export function applyFill(
   { slippageBps = 0, feeBps = 0, kind = "market", qty = 0, costs = {} } = {}
 ) {
   const model = costs || {};
-  const modelSlippageBps = Number.isFinite(model.slippageBps)
-    ? model.slippageBps
-    : slippageBps;
-  const modelFeeBps = Number.isFinite(model.commissionBps)
-    ? model.commissionBps
-    : feeBps;
-  const effectiveSlippageBps = resolveSlippageBps(
-    kind,
-    modelSlippageBps,
-    model.slippageByKind
-  );
-  const halfSpreadBps = Number.isFinite(model.spreadBps)
-    ? model.spreadBps / 2
-    : 0;
+  const modelSlippageBps = Number.isFinite(model.slippageBps) ? model.slippageBps : slippageBps;
+  const modelFeeBps = Number.isFinite(model.commissionBps) ? model.commissionBps : feeBps;
+  const effectiveSlippageBps = resolveSlippageBps(kind, modelSlippageBps, model.slippageByKind);
+  const halfSpreadBps = Number.isFinite(model.spreadBps) ? model.spreadBps / 2 : 0;
 
   const slippage = ((effectiveSlippageBps + halfSpreadBps) / 10000) * price;
   const filledPrice = side === "long" ? price + slippage : price - slippage;
@@ -38,16 +28,13 @@ export function applyFill(
     ((modelFeeBps || 0) / 10000) * Math.abs(filledPrice) +
     (Number.isFinite(model.commissionPerUnit) ? model.commissionPerUnit : 0);
   const variableFeeTotal = variableFeePerUnit * Math.max(0, qty);
-  const fixedFeeTotal = Number.isFinite(model.commissionPerOrder)
-    ? model.commissionPerOrder
-    : 0;
+  const fixedFeeTotal = Number.isFinite(model.commissionPerOrder) ? model.commissionPerOrder : 0;
   const grossFeeTotal = variableFeeTotal + fixedFeeTotal;
   const feeTotal = Math.max(
     Number.isFinite(model.minCommission) ? model.minCommission : 0,
     grossFeeTotal
   );
-  const feePerUnit =
-    qty > 0 ? feeTotal / qty : variableFeePerUnit;
+  const feePerUnit = qty > 0 ? feeTotal / qty : variableFeePerUnit;
 
   return { price: filledPrice, fee: feePerUnit, feeTotal };
 }
@@ -63,21 +50,12 @@ export function clampStop(marketPrice, proposedStop, side, oco) {
 export function touchedLimit(side, limitPrice, bar, mode = "intrabar") {
   if (!bar || limitPrice === undefined || limitPrice === null) return false;
   if (mode === "close") {
-    return side === "long"
-      ? bar.close <= limitPrice
-      : bar.close >= limitPrice;
+    return side === "long" ? bar.close <= limitPrice : bar.close >= limitPrice;
   }
   return side === "long" ? bar.low <= limitPrice : bar.high >= limitPrice;
 }
 
-export function ocoExitCheck({
-  side,
-  stop,
-  tp,
-  bar,
-  mode = "intrabar",
-  tieBreak = "pessimistic",
-}) {
+export function ocoExitCheck({ side, stop, tp, bar, mode = "intrabar", tieBreak = "pessimistic" }) {
   if (mode === "close") {
     const close = bar.close;
     if (side === "long") {
@@ -94,9 +72,7 @@ export function ocoExitCheck({
   const hitTarget = side === "long" ? bar.high >= tp : bar.low <= tp;
 
   if (hitStop && hitTarget) {
-    return tieBreak === "optimistic"
-      ? { hit: "TP", px: tp }
-      : { hit: "SL", px: stop };
+    return tieBreak === "optimistic" ? { hit: "TP", px: tp } : { hit: "SL", px: stop };
   }
 
   if (hitStop) return { hit: "SL", px: stop };
@@ -123,10 +99,7 @@ export function estimateBarMs(candles) {
     if (deltas.length) {
       deltas.sort((a, b) => a - b);
       const middle = Math.floor(deltas.length / 2);
-      const median =
-        deltas.length % 2
-          ? deltas[middle]
-          : (deltas[middle - 1] + deltas[middle]) / 2;
+      const median = deltas.length % 2 ? deltas[middle] : (deltas[middle - 1] + deltas[middle]) / 2;
       return Math.max(60e3, Math.min(median, 60 * 60e3));
     }
   }
@@ -151,7 +124,6 @@ export function dayKeyET(timeMs) {
   const anchor = new Date(
     Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate(), 0, 0, 0)
   );
-  const pseudoEtTime =
-    anchor.getTime() + hoursET * 60 * 60 * 1000 + minutesETDay * 60 * 1000;
+  const pseudoEtTime = anchor.getTime() + hoursET * 60 * 60 * 1000 + minutesETDay * 60 * 1000;
   return dayKeyUTC(pseudoEtTime);
 }

package/src/engine/portfolio.js

@@ -1,57 +1,62 @@
 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);
-    }
-  }
+function describeValue(value) {
+  if (Array.isArray(value)) return `array(length=${value.length})`;
+  if (value === null) return "null";
+  return typeof value;
+}
 
-  const times = [...timeline].sort((left, right) => left - right);
-  if (!times.length) {
-    return [{ time: 0, timestamp: 0, equity: totalEquity }];
-  }
+function buildPortfolioPoint(time, equity, lockedCapital, availableCapital) {
+  return {
+    time,
+    timestamp: time,
+    equity,
+    lockedCapital,
+    availableCapital,
+  };
+}
 
-  const states = systemRuns.map((run) => ({
-    points: run.result.eqSeries || [],
-    index: 0,
-    lastEquity: run.allocationEquity,
-  }));
+function stableSystemOrder(left, right) {
+  return left.index - right.index;
+}
 
-  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 hashedOrderScore(index, time, seed) {
+  let value = (Number(time) ^ Math.imul(index + 1, 0x9e3779b1) ^ (seed | 0)) >>> 0;
+  value = Math.imul(value ^ (value >>> 16), 0x85ebca6b) >>> 0;
+  value = Math.imul(value ^ (value >>> 13), 0xc2b2ae35) >>> 0;
+  return (value ^ (value >>> 16)) >>> 0;
+}
+
+function orderActiveSystems(active, nextTime, processingOrder, shuffleSeed) {
+  if (processingOrder !== "shuffle") {
+    active.sort(stableSystemOrder);
+    return;
+  }
 
-    return { time, timestamp: time, equity };
+  active.sort((left, right) => {
+    const leftScore = hashedOrderScore(left.index, nextTime, shuffleSeed);
+    const rightScore = hashedOrderScore(right.index, nextTime, shuffleSeed);
+    if (leftScore !== rightScore) return leftScore - rightScore;
+    return stableSystemOrder(left, right);
   });
 }
 
-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 +67,83 @@ 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. `processingOrder` can be
+ * set to `"shuffle"` for fairness testing when multiple systems act on the same bar.
  */
 export function backtestPortfolio({
   systems = [],
@@ -80,39 +151,138 @@ export function backtestPortfolio({
   allocation = "equal",
   collectEqSeries = true,
   collectReplay = false,
+  maxDailyLossPct = 0,
+  processingOrder = "sequential",
+  shuffleSeed = 0,
 } = {}) {
   if (!Array.isArray(systems) || systems.length === 0) {
-    throw new Error("backtestPortfolio() requires a non-empty systems array");
+    throw new Error(
+      `backtestPortfolio() requires a non-empty systems array, got ${describeValue(systems)}`
+    );
+  }
+  if (processingOrder !== "sequential" && processingOrder !== "shuffle") {
+    throw new Error(
+      `backtestPortfolio() processingOrder must be "sequential" or "shuffle", got ${processingOrder}`
+    );
   }
 
   const weights =
     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");
+    throw new Error(
+      `backtestPortfolio() requires positive allocation weights, got allocation=${allocation}`
+    );
   }
 
-  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;
+    orderActiveSystems(active, nextTime, processingOrder, shuffleSeed);
+
+    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 +290,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 +298,13 @@ 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 openPositions = systemResults.flatMap((run) =>
+    (run.result.openPositions || []).map((position) => ({
+      ...position,
+      symbol: position.symbol || run.symbol,
+    }))
+  );
+  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({
@@ -147,14 +322,10 @@ export function backtestPortfolio({
     range: undefined,
     trades,
     positions,
+    openPositions,
     metrics,
     eqSeries,
     replay,
-    systems: systemRuns.map((run) => ({
-      symbol: run.symbol,
-      weight: run.weight / totalWeight,
-      equity: run.allocationEquity,
-      result: run.result,
-    })),
+    systems: systemResults,
   };
 }