tradelab 1.0.1 → 1.2.0

package/src/engine/asyncSignal.js

@@ -0,0 +1,28 @@
+export class BudgetExceededError extends Error {
+  constructor(ms) {
+    super(`signal() exceeded its ${ms}ms per-bar budget`);
+    this.name = "BudgetExceededError";
+    this.budgetMs = ms;
+  }
+}
+
+/**
+ * Race a promise against a per-bar time budget. `budgetMs` of 0/undefined
+ * disables the timeout. Rejects with BudgetExceededError on overrun.
+ */
+export function withBudget(promise, budgetMs) {
+  if (!budgetMs || budgetMs <= 0) return Promise.resolve(promise);
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(new BudgetExceededError(budgetMs)), budgetMs);
+    Promise.resolve(promise).then(
+      (value) => {
+        clearTimeout(timer);
+        resolve(value);
+      },
+      (err) => {
+        clearTimeout(timer);
+        reject(err);
+      }
+    );
+  });
+}

package/src/engine/backtest.js

@@ -12,6 +12,7 @@ import {
   estimateBarMs,
   dayKeyUTC,
   dayKeyET,
+  financingCost,
 } from "./execution.js";
 
 function asNumber(value) {
@@ -154,6 +155,7 @@ function mergeOptions(options) {
     maxSlipROnFill: options.maxSlipROnFill ?? 0.4,
     collectEqSeries: options.collectEqSeries ?? true,
     collectReplay: options.collectReplay ?? true,
+    benchmarkReturns: Array.isArray(options.benchmarkReturns) ? options.benchmarkReturns : null,
     strict: options.strict ?? false,
   };
 }
@@ -305,7 +307,14 @@ export function backtest(rawOptions) {
     const entryFill = openPos.entryFill;
     const grossPnl = (exitPx - entryFill) * direction * qty;
     const entryFeePortion = (openPos.entryFeeTotal || 0) * (qty / openPos.initSize);
-    const pnl = grossPnl - entryFeePortion - exitFeeTotal;
+    const financing = financingCost({
+      side: openPos.side,
+      notional: entryFill * qty,
+      fromMs: openPos.openTime,
+      toMs: time,
+      costs,
+    });
+    const pnl = grossPnl - entryFeePortion - exitFeeTotal - financing;
 
     currentEquity += pnl;
     dayPnl += pnl;
@@ -349,6 +358,7 @@ export function backtest(rawOptions) {
         time,
         reason,
         pnl,
+        financing,
         exitATR: openPos._lastATR ?? undefined,
       },
       mfeR: openPos._mfeR ?? 0,
@@ -872,6 +882,8 @@ export function backtest(rawOptions) {
     candles,
     estBarMs: estimatedBarMs,
     eqSeries,
+    interval: options.interval,
+    benchmarkReturns: options.benchmarkReturns,
   });
   const positions = closed.filter((trade) => trade.exit.reason !== "SCALE");
   const lastPrice = asNumber(candles[candles.length - 1]?.close);

package/src/engine/backtestAsync.js

@@ -0,0 +1,27 @@
+import { BarSystemRunner } from "./barSystemRunner.js";
+import { withBudget } from "./asyncSignal.js";
+
+/**
+ * Async sibling of backtest(). Identical result shape, but `signal()` may return
+ * a Promise. Each bar's signal is raced against `signalBudgetMs` (0 disables).
+ *
+ * Built on BarSystemRunner so position/pending/exit logic is shared with the
+ * sync engine and portfolio mode.
+ */
+export async function backtestAsync(rawOptions = {}) {
+  const budgetMs = rawOptions.signalBudgetMs ?? 0;
+  const userSignal = rawOptions.signal;
+  const budgetedSignal = (context) =>
+    withBudget(
+      Promise.resolve().then(() => userSignal(context)),
+      budgetMs
+    );
+
+  const runner = new BarSystemRunner({ ...rawOptions, signal: budgetedSignal });
+
+  while (runner.hasNext()) {
+    await runner.stepAsync({ signalEquity: runner.getMarkedEquity() });
+  }
+
+  return runner.buildResult();
+}

package/src/engine/backtestTicks.js

@@ -1,6 +1,6 @@
 import { buildMetrics } from "../metrics/buildMetrics.js";
 import { calculatePositionSize } from "../utils/positionSizing.js";
-import { applyFill, dayKeyUTC, ocoExitCheck, roundStep } from "./execution.js";
+import { applyFill, dayKeyUTC, financingCost, ocoExitCheck, roundStep } from "./execution.js";
 
 function asNumber(value) {
   const numeric = Number(value);
@@ -163,6 +163,7 @@ export function backtestTicks({
   collectEqSeries = true,
   collectReplay = true,
   queueFillProbability = 1,
+  seed = "tradelab-ticks",
   oco = {},
 } = {}) {
   if (!Array.isArray(ticks) || ticks.length === 0) {
@@ -235,7 +236,14 @@ export function backtestTicks({
     });
     const direction = open.side === "long" ? 1 : -1;
     const grossPnl = (price - open.entryFill) * direction * open.size;
-    const pnl = grossPnl - (open.entryFeeTotal || 0) - feeTotal;
+    const financing = financingCost({
+      side: open.side,
+      notional: open.entryFill * open.size,
+      fromMs: open.openTime,
+      toMs: tick.time,
+      costs,
+    });
+    const pnl = grossPnl - (open.entryFeeTotal || 0) - feeTotal - financing;
     currentEquity += pnl;
     dayPnl += pnl;
     const trade = {
@@ -245,6 +253,7 @@ export function backtestTicks({
         time: tick.time,
         reason,
         pnl,
+        financing,
       },
     };
     trades.push(trade);
@@ -343,6 +352,7 @@ export function backtestTicks({
         if (
           touched &&
           deterministicFill(queueFillProbability, [
+            seed,
             symbol,
             tick.time,
             pending.entry,
@@ -462,6 +472,7 @@ export function backtestTicks({
         ? Math.max(1, normalizedTicks[1].time - normalizedTicks[0].time)
         : 1,
     eqSeries,
+    interval,
   });
 
   return {

package/src/engine/barSystemRunner.js

@@ -5,6 +5,7 @@ import { normalizeCandles } from "../data/csv.js";
 import {
   applyFill,
   clampStop,
+  financingCost,
   touchedLimit,
   ocoExitCheck,
   isEODBar,
@@ -63,6 +64,17 @@ export function callSignalWithContext({ signal, context, index, bar, symbol }) {
   }
 }
 
+export async function callSignalWithContextAsync({ signal, context, index, bar, symbol }) {
+  try {
+    return await signal(context);
+  } catch (error) {
+    const cause = error instanceof Error ? error.message : String(error);
+    throw new Error(
+      `signal() threw at index=${index}, time=${formatIsoTime(bar?.time)}, symbol=${symbol}: ${cause}`
+    );
+  }
+}
+
 export function snapshotOpenPosition(open, markPrice) {
   if (!open) return null;
   const entryPrice = open.entryFill ?? open.entry;
@@ -305,7 +317,14 @@ export class BarSystemRunner {
     const entryFill = openPos.entryFill;
     const grossPnl = (exitPx - entryFill) * direction * qty;
     const entryFeePortion = (openPos.entryFeeTotal || 0) * (qty / openPos.initSize);
-    const pnl = grossPnl - entryFeePortion - exitFeeTotal;
+    const financing = financingCost({
+      side: openPos.side,
+      notional: entryFill * qty,
+      fromMs: openPos.openTime,
+      toMs: time,
+      costs: this.options.costs,
+    });
+    const pnl = grossPnl - entryFeePortion - exitFeeTotal - financing;
 
     this.currentEquity += pnl;
     this.dayPnl += pnl;
@@ -350,6 +369,7 @@ export class BarSystemRunner {
         time,
         reason,
         pnl,
+        financing,
         exitATR: openPos._lastATR ?? undefined,
       },
       mfeR: openPos._mfeR ?? 0,
@@ -544,8 +564,8 @@ export class BarSystemRunner {
     };
   }
 
-  step({ signalEquity, canTrade = true, resolveEntrySize } = {}) {
-    if (!this.hasNext()) return null;
+  _preSignal({ signalEquity, canTrade = true, resolveEntrySize } = {}) {
+    if (!this.hasNext()) return { handled: true, bar: null };
 
     const bar = this.candles[this.index];
     this.history.push(bar);
@@ -929,52 +949,60 @@ export class BarSystemRunner {
       if (this.cooldown > 0) this.cooldown -= 1;
       this.recordFrame(bar);
       this.index += 1;
-      return bar;
+      return { handled: true, bar };
     }
 
     if (!canTrade || dailyLossHit || dailyTradeCapHit) {
       this.pending = null;
       this.recordFrame(bar);
       this.index += 1;
-      return bar;
+      return { handled: true, bar };
     }
 
-    if (!this.pending) {
-      const rawSignal = callSignalWithContext({
-        signal: this.options.signal,
-        context: this.buildSignalContext(this.index, bar, signalEquity),
-        index: this.index,
-        bar,
-        symbol: this.symbol,
-      });
-      const nextSignal = normalizeSignal(rawSignal, bar, this.options.finalTP_R);
-
-      if (nextSignal) {
-        const signalRiskFraction = Number.isFinite(nextSignal.riskFraction)
-          ? nextSignal.riskFraction
-          : Number.isFinite(nextSignal.riskPct)
-            ? nextSignal.riskPct / 100
-            : this.options.riskPct / 100;
-        const expiryBars = nextSignal._entryExpiryBars ?? 5;
-        this.pending = {
-          side: nextSignal.side,
-          entry: nextSignal.entry,
-          stop: nextSignal.stop,
-          tp: nextSignal.takeProfit,
-          riskFrac: signalRiskFraction,
-          fixedQty: nextSignal.qty,
-          expiresAt: this.index + Math.max(1, expiryBars),
-          startedAtIndex: this.index,
-          meta: nextSignal,
-          plannedRiskAbs: Math.abs(nextSignal._initRisk ?? nextSignal.entry - nextSignal.stop),
-        };
-
-        if (touchedLimit(this.pending.side, this.pending.entry, bar, trigger)) {
-          if (
-            !this.openFromPending(bar, signalEquity, this.pending.entry, "limit", resolveEntrySize)
-          ) {
-            this.pending = null;
-          }
+    if (this.pending) {
+      this.recordFrame(bar);
+      this.index += 1;
+      return { handled: true, bar };
+    }
+
+    return {
+      handled: false,
+      bar,
+      trigger,
+      signalEquity,
+      resolveEntrySize,
+    };
+  }
+
+  _applyRawSignal(rawSignal, pre) {
+    const { bar, trigger, signalEquity, resolveEntrySize } = pre;
+    const nextSignal = normalizeSignal(rawSignal, bar, this.options.finalTP_R);
+
+    if (nextSignal) {
+      const signalRiskFraction = Number.isFinite(nextSignal.riskFraction)
+        ? nextSignal.riskFraction
+        : Number.isFinite(nextSignal.riskPct)
+          ? nextSignal.riskPct / 100
+          : this.options.riskPct / 100;
+      const expiryBars = nextSignal._entryExpiryBars ?? 5;
+      this.pending = {
+        side: nextSignal.side,
+        entry: nextSignal.entry,
+        stop: nextSignal.stop,
+        tp: nextSignal.takeProfit,
+        riskFrac: signalRiskFraction,
+        fixedQty: nextSignal.qty,
+        expiresAt: this.index + Math.max(1, expiryBars),
+        startedAtIndex: this.index,
+        meta: nextSignal,
+        plannedRiskAbs: Math.abs(nextSignal._initRisk ?? nextSignal.entry - nextSignal.stop),
+      };
+
+      if (touchedLimit(this.pending.side, this.pending.entry, bar, trigger)) {
+        if (
+          !this.openFromPending(bar, signalEquity, this.pending.entry, "limit", resolveEntrySize)
+        ) {
+          this.pending = null;
         }
       }
     }
@@ -984,6 +1012,32 @@ export class BarSystemRunner {
     return bar;
   }
 
+  step(options = {}) {
+    const pre = this._preSignal(options);
+    if (pre.handled) return pre.bar;
+    const rawSignal = callSignalWithContext({
+      signal: this.options.signal,
+      context: this.buildSignalContext(this.index, pre.bar, pre.signalEquity),
+      index: this.index,
+      bar: pre.bar,
+      symbol: this.symbol,
+    });
+    return this._applyRawSignal(rawSignal, pre);
+  }
+
+  async stepAsync(options = {}) {
+    const pre = this._preSignal(options);
+    if (pre.handled) return pre.bar;
+    const rawSignal = await callSignalWithContextAsync({
+      signal: this.options.signal,
+      context: this.buildSignalContext(this.index, pre.bar, pre.signalEquity),
+      index: this.index,
+      bar: pre.bar,
+      symbol: this.symbol,
+    });
+    return this._applyRawSignal(rawSignal, pre);
+  }
+
   buildResult() {
     const metrics = buildMetrics({
       closed: this.closed,
@@ -992,6 +1046,7 @@ export class BarSystemRunner {
       candles: this.candles,
       estBarMs: this.estimatedBarMs,
       eqSeries: this.eqSeries,
+      interval: this.options.interval,
     });
     const positions = this.closed.filter((trade) => trade.exit.reason !== "SCALE");
     const lastPrice = asNumber(this.candles[this.candles.length - 1]?.close);

package/src/engine/execution.js

@@ -127,3 +127,42 @@ export function dayKeyET(timeMs) {
   const pseudoEtTime = anchor.getTime() + hoursET * 60 * 60 * 1000 + minutesETDay * 60 * 1000;
   return dayKeyUTC(pseudoEtTime);
 }
+
+const MS_PER_YEAR = 365 * 24 * 60 * 60 * 1000;
+
+/**
+ * Count funding boundaries in the half-open interval (fromMs, toMs], given a
+ * funding `intervalMs` cadence anchored at `anchorMs`.
+ */
+export function fundingEvents(fromMs, toMs, intervalMs, anchorMs = 0) {
+  if (!(intervalMs > 0) || toMs <= fromMs) return 0;
+  const firstK = Math.floor((fromMs - anchorMs) / intervalMs) + 1;
+  const lastK = Math.floor((toMs - anchorMs) / intervalMs);
+  return Math.max(0, lastK - firstK + 1);
+}
+
+/**
+ * Time-based financing cost for holding `notional` from `fromMs` to `toMs`.
+ * Positive return = cost to the position (subtract from PnL).
+ */
+export function financingCost({ side, notional, fromMs, toMs, costs }) {
+  const model = costs || {};
+  const absNotional = Math.abs(notional);
+  let cost = 0;
+
+  if (model.carry) {
+    const annualBps =
+      side === "long" ? (model.carry.longAnnualBps ?? 0) : (model.carry.shortAnnualBps ?? 0);
+    const years = Math.max(0, toMs - fromMs) / MS_PER_YEAR;
+    cost += absNotional * (annualBps / 10000) * years;
+  }
+
+  const funding = model.funding;
+  if (funding && funding.intervalMs > 0 && Number.isFinite(funding.rateBps)) {
+    const count = fundingEvents(fromMs, toMs, funding.intervalMs, funding.anchorMs ?? 0);
+    const perEvent = absNotional * (funding.rateBps / 10000);
+    cost += (side === "long" ? 1 : -1) * perEvent * count;
+  }
+
+  return cost;
+}

package/src/engine/grid.js

@@ -0,0 +1,15 @@
+/**
+ * Expand a parameter grid into an array of parameter-set objects.
+ * Array values are swept; scalar values are held fixed across all sets.
+ */
+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 })));
+    },
+    [{}]
+  );
+}

package/src/engine/llmSignal.js

@@ -0,0 +1,84 @@
+import { withBudget } from "./asyncSignal.js";
+
+function isArrayIndexKey(property) {
+  if (typeof property !== "string") return false;
+  const n = Number(property);
+  return Number.isInteger(n) && n >= 0;
+}
+
+function noLookaheadView(candles, index) {
+  return new Proxy(candles, {
+    get(target, property, receiver) {
+      if (isArrayIndexKey(property) && Number(property) > index) {
+        throw new Error(
+          `LlmSignal: lookahead access to candles[${String(property)}] (current index ${index})`
+        );
+      }
+      return Reflect.get(target, property, receiver);
+    },
+  });
+}
+
+/**
+ * Wraps an async model-backed decision function for use as a tradelab signal.
+ *
+ * - Caches by bar time: resolve() runs at most once per bar.
+ * - Enforces a per-bar `budgetMs` time budget.
+ * - Exposes a no-lookahead candle view to resolve().
+ * - Logs every decision (context summary, result or error) in `this.log`.
+ *
+ * `onError`: "skip" (return null, default) or "throw".
+ * Use the instance's `.signal` bound method as the engine's `signal` option.
+ */
+export class LlmSignal {
+  constructor({ resolve, budgetMs = 0, onError = "skip" } = {}) {
+    if (typeof resolve !== "function") {
+      throw new Error("LlmSignal requires a resolve(context) function");
+    }
+    this.resolve = resolve;
+    this.budgetMs = budgetMs;
+    this.onError = onError;
+    this.log = [];
+    this._cache = new Map();
+    this.signal = this.signal.bind(this);
+  }
+
+  async signal(context) {
+    const key = context.bar?.time ?? context.index;
+    if (this._cache.has(key)) return this._cache.get(key);
+
+    const safeContext = {
+      ...context,
+      candles: noLookaheadView(context.candles, context.index),
+    };
+
+    const startedAt = Date.now();
+    try {
+      const result = await withBudget(
+        Promise.resolve().then(() => this.resolve(safeContext)),
+        this.budgetMs
+      );
+      this._cache.set(key, result ?? null);
+      this.log.push({
+        index: context.index,
+        time: context.bar?.time,
+        close: context.bar?.close,
+        latencyMs: Date.now() - startedAt,
+        result: result ?? null,
+      });
+      return result ?? null;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      this.log.push({
+        index: context.index,
+        time: context.bar?.time,
+        close: context.bar?.close,
+        latencyMs: Date.now() - startedAt,
+        error: message,
+      });
+      this._cache.set(key, null);
+      if (this.onError === "throw") throw error;
+      return null;
+    }
+  }
+}

package/src/engine/optimize.js

@@ -0,0 +1,110 @@
+import { Worker } from "node:worker_threads";
+import os from "node:os";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+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;
+}
+
+function callerModuleDir() {
+  const stack = new Error().stack || "";
+  const lines = stack.split("\n").slice(1);
+  const match = lines
+    .map((line) => line.match(/(?:\()?(file:\/\/\/[^\s)]+|\/[^\s)]+):\d+:\d+/))
+    .find(Boolean);
+  if (!match) return process.cwd();
+  const filePath = match[1].startsWith("file://") ? fileURLToPath(match[1]) : match[1];
+  return path.dirname(filePath);
+}
+
+function workerUrl() {
+  const here = callerModuleDir();
+  const candidates = [
+    path.join(here, "optimizeWorker.js"),
+    path.join(here, "..", "..", "src", "engine", "optimizeWorker.js"),
+    path.join(process.cwd(), "src", "engine", "optimizeWorker.js"),
+  ];
+  return pathToFileURL(candidates.find((candidate) => existsSync(candidate)) || candidates[0]);
+}
+
+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(workerUrl(), {
+        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);
+    }
+  });
+}

package/src/engine/optimizeWorker.js

@@ -0,0 +1,67 @@
+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`
+  );
+}
+
+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" });