tradelab 0.4.0 → 1.0.0

package/src/live/engine/stateManager.js

@@ -0,0 +1,112 @@
+function qtyCloseEnough(a, b, tolerancePct = 0.05) {
+  const left = Math.abs(Number(a) || 0);
+  const right = Math.abs(Number(b) || 0);
+  if (left === 0 && right === 0) return true;
+  const baseline = Math.max(left, right, 1e-12);
+  return Math.abs(left - right) / baseline <= tolerancePct;
+}
+
+function sideMatches(openPosition, brokerPosition) {
+  if (!openPosition || !brokerPosition) return false;
+  const openSide = openPosition.side;
+  const brokerSide = brokerPosition.side;
+  return openSide === brokerSide;
+}
+
+/**
+ * Coordinates state persistence and restart reconciliation.
+ */
+export class StateManager {
+  constructor({ storage }) {
+    this.storage = storage;
+  }
+
+  async load(namespace) {
+    return this.storage.load(namespace);
+  }
+
+  async save(namespace, state) {
+    await this.storage.save(namespace, {
+      ...state,
+      savedAt: Date.now(),
+    });
+  }
+
+  async appendTrade(namespace, trade) {
+    await this.storage.appendTrade(namespace, trade);
+  }
+
+  async appendEquityPoint(namespace, point) {
+    await this.storage.appendEquityPoint(namespace, point);
+  }
+
+  async loadTrades(namespace) {
+    return this.storage.loadTrades(namespace);
+  }
+
+  async loadEquityCurve(namespace) {
+    return this.storage.loadEquityCurve(namespace);
+  }
+
+  async clear(namespace) {
+    await this.storage.clear(namespace);
+  }
+
+  reconcile({ persistedState, brokerPositions = [], symbol }) {
+    const report = {
+      status: "ok",
+      action: "none",
+      message: "no reconciliation needed",
+      adoptedPosition: null,
+      mismatch: null,
+    };
+
+    const persistedOpen = persistedState?.openPosition || null;
+    const brokerForSymbol = brokerPositions.find((position) => position.symbol === symbol) || null;
+
+    if (persistedOpen && brokerForSymbol) {
+      const sameSide = sideMatches(persistedOpen, brokerForSymbol);
+      const similarQty = qtyCloseEnough(
+        persistedOpen.size ?? persistedOpen.qty,
+        brokerForSymbol.qty
+      );
+      if (sameSide && similarQty) {
+        report.action = "adopt-broker";
+        report.message = "persisted and broker positions matched";
+        report.adoptedPosition = {
+          ...persistedOpen,
+          size: brokerForSymbol.qty,
+          entryFill: brokerForSymbol.avgEntry ?? persistedOpen.entryFill ?? persistedOpen.entry,
+        };
+        return report;
+      }
+
+      report.status = "error";
+      report.action = "mismatch";
+      report.message = "persisted and broker positions mismatch";
+      report.mismatch = { persisted: persistedOpen, broker: brokerForSymbol };
+      return report;
+    }
+
+    if (persistedOpen && !brokerForSymbol) {
+      report.status = "warn";
+      report.action = "closed-externally";
+      report.message = "persisted open position missing at broker";
+      return report;
+    }
+
+    if (!persistedOpen && brokerForSymbol) {
+      report.status = "warn";
+      report.action = "external-position";
+      report.message = "broker has external position not present in persisted state";
+      report.adoptedPosition = null;
+      return report;
+    }
+
+    return report;
+  }
+}
+
+export function createStateManager(options) {
+  return new StateManager(options);
+}

package/src/live/events.js

@@ -0,0 +1,48 @@
+import { EventEmitter } from "node:events";
+
+export const LIVE_EVENTS = [
+  "signal",
+  "order:submitted",
+  "order:filled",
+  "order:canceled",
+  "order:rejected",
+  "order:modified",
+  "position:opened",
+  "position:updated",
+  "position:closed",
+  "equity:update",
+  "risk:warning",
+  "risk:halt",
+  "bar",
+  "tick",
+  "error",
+  "connected",
+  "disconnected",
+  "reconnecting",
+  "shutdown",
+  "stateRestored",
+  "reconciled",
+];
+
+/**
+ * Lightweight event bus used by live trading components.
+ *
+ * Events are emitted on their native channel plus the wildcard `*` channel for
+ * consumers that want to capture all traffic (for logging/monitoring).
+ */
+export class EventBus extends EventEmitter {
+  emitEvent(event, payload = {}) {
+    this.emit(event, payload);
+    this.emit("*", { event, payload });
+    return true;
+  }
+
+  onAny(handler) {
+    this.on("*", handler);
+    return () => this.off("*", handler);
+  }
+}
+
+export function createEventBus() {
+  return new EventBus();
+}

package/src/live/feed/brokerFeed.js

@@ -0,0 +1,35 @@
+import { FeedProvider } from "./interface.js";
+
+/**
+ * Feed provider that delegates to a broker adapter.
+ */
+export class BrokerFeed extends FeedProvider {
+  constructor({ broker }) {
+    super();
+    this.broker = broker;
+  }
+
+  async connect() {
+    return undefined;
+  }
+
+  async disconnect() {
+    return undefined;
+  }
+
+  subscribeBars(symbol, interval, handler) {
+    return this.broker.subscribeBars(symbol, interval, handler);
+  }
+
+  subscribeTicks(symbol, handler) {
+    return this.broker.subscribeTrades(symbol, handler);
+  }
+
+  async getHistoricalBars(symbol, interval, count) {
+    return this.broker.getHistoricalBars(symbol, interval, count);
+  }
+}
+
+export function createBrokerFeed(options) {
+  return new BrokerFeed(options);
+}

package/src/live/feed/interface.js

@@ -0,0 +1,28 @@
+function notImplemented(method) {
+  throw new Error(`FeedProvider.${method}() not implemented`);
+}
+
+/**
+ * Base class for feed providers.
+ */
+export class FeedProvider {
+  async connect() {
+    notImplemented("connect");
+  }
+
+  async disconnect() {
+    notImplemented("disconnect");
+  }
+
+  subscribeBars(_symbol, _interval, _handler) {
+    notImplemented("subscribeBars");
+  }
+
+  subscribeTicks(_symbol, _handler) {
+    notImplemented("subscribeTicks");
+  }
+
+  async getHistoricalBars(_symbol, _interval, _count) {
+    notImplemented("getHistoricalBars");
+  }
+}

package/src/live/feed/pollingFeed.js

@@ -0,0 +1,105 @@
+import { FeedProvider } from "./interface.js";
+
+function keyFor(symbol, interval) {
+  return `${symbol}::${interval}`;
+}
+
+/**
+ * REST polling feed suitable for serverless/cron mode.
+ */
+export class PollingFeed extends FeedProvider {
+  constructor({ broker, pollIntervalMs = 60_000, defaultBarsPerPoll = 2 } = {}) {
+    super();
+    this.broker = broker;
+    this.pollIntervalMs = Math.max(500, Number(pollIntervalMs) || 60_000);
+    this.defaultBarsPerPoll = Math.max(1, Number(defaultBarsPerPoll) || 2);
+    this.barSubscriptions = new Map();
+    this.tickSubscriptions = new Map();
+    this.lastEmittedByStream = new Map();
+    this.timer = null;
+    this.connected = false;
+  }
+
+  async connect() {
+    this.connected = true;
+  }
+
+  async disconnect() {
+    this.connected = false;
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+
+  subscribeBars(symbol, interval, handler) {
+    const streamKey = keyFor(symbol, interval);
+    const list = this.barSubscriptions.get(streamKey) || [];
+    list.push(handler);
+    this.barSubscriptions.set(streamKey, list);
+    return {
+      unsubscribe: () => {
+        const current = this.barSubscriptions.get(streamKey) || [];
+        this.barSubscriptions.set(
+          streamKey,
+          current.filter((candidate) => candidate !== handler)
+        );
+      },
+    };
+  }
+
+  subscribeTicks(symbol, handler) {
+    const list = this.tickSubscriptions.get(symbol) || [];
+    list.push(handler);
+    this.tickSubscriptions.set(symbol, list);
+    return {
+      unsubscribe: () => {
+        const current = this.tickSubscriptions.get(symbol) || [];
+        this.tickSubscriptions.set(
+          symbol,
+          current.filter((candidate) => candidate !== handler)
+        );
+      },
+    };
+  }
+
+  async getHistoricalBars(symbol, interval, count) {
+    return this.broker.getHistoricalBars(symbol, interval, count);
+  }
+
+  async pollOnce() {
+    const streams = [...this.barSubscriptions.keys()];
+    for (const stream of streams) {
+      const [symbol, interval] = stream.split("::");
+      const bars = await this.broker.getHistoricalBars(symbol, interval, this.defaultBarsPerPoll);
+      const ordered = [...bars].sort((left, right) => left.time - right.time);
+      const lastSeen = this.lastEmittedByStream.get(stream) ?? -Infinity;
+      const next = ordered.filter((bar) => bar.time > lastSeen);
+      if (!next.length) continue;
+      const handlers = this.barSubscriptions.get(stream) || [];
+      for (const bar of next) {
+        for (const handler of handlers) {
+          await handler(bar);
+        }
+      }
+      this.lastEmittedByStream.set(stream, next[next.length - 1].time);
+    }
+  }
+
+  startPolling() {
+    if (this.timer) return;
+    this.timer = setInterval(() => {
+      this.pollOnce().catch(() => {});
+    }, this.pollIntervalMs);
+  }
+
+  stopPolling() {
+    if (!this.timer) return;
+    clearInterval(this.timer);
+    this.timer = null;
+  }
+}
+
+export function createPollingFeed(options) {
+  return new PollingFeed(options);
+}

package/src/live/index.js

@@ -0,0 +1,27 @@
+export { EventBus, LIVE_EVENTS, createEventBus } from "./events.js";
+export { LiveLogger, createLogger } from "./logger.js";
+export { BrokerClock, createClock } from "./clock.js";
+
+export { BrokerAdapter } from "./broker/interface.js";
+export { AlpacaBroker, createAlpacaBroker } from "./broker/alpaca.js";
+export { BinanceBroker, createBinanceBroker } from "./broker/binance.js";
+export { CoinbaseBroker, createCoinbaseBroker } from "./broker/coinbase.js";
+export {
+  InteractiveBrokersBroker,
+  createInteractiveBrokersBroker,
+} from "./broker/interactiveBrokers.js";
+
+export { FeedProvider } from "./feed/interface.js";
+export { BrokerFeed, createBrokerFeed } from "./feed/brokerFeed.js";
+export { PollingFeed, createPollingFeed } from "./feed/pollingFeed.js";
+
+export { StorageProvider } from "./storage/interface.js";
+export { JsonFileStorage, createJsonFileStorage } from "./storage/jsonFileStorage.js";
+
+export { CandleAggregator, createCandleAggregator } from "./engine/candleAggregator.js";
+export { RiskManager, createRiskManager } from "./engine/riskManager.js";
+export { StateManager, createStateManager } from "./engine/stateManager.js";
+export { PaperEngine, createPaperEngine } from "./engine/paperEngine.js";
+export { LiveEngine, createLiveEngine } from "./engine/liveEngine.js";
+
+export { LiveOrchestrator, createLiveOrchestrator } from "./orchestrator.js";

package/src/live/logger.js

@@ -0,0 +1,82 @@
+const LOG_PRIORITIES = {
+  debug: 10,
+  info: 20,
+  warn: 30,
+  error: 40,
+  silent: 100,
+};
+
+function normalizeLevel(level) {
+  return Object.prototype.hasOwnProperty.call(LOG_PRIORITIES, level) ? level : "info";
+}
+
+/**
+ * Structured JSON logger for live components.
+ */
+export class LiveLogger {
+  constructor({ level = "info", stream = process.stdout } = {}) {
+    this.level = normalizeLevel(level);
+    this.stream = stream;
+    this._unsub = null;
+  }
+
+  shouldLog(level) {
+    return LOG_PRIORITIES[level] >= LOG_PRIORITIES[this.level];
+  }
+
+  write(level, message, fields = {}) {
+    const normalizedLevel = normalizeLevel(level);
+    if (!this.shouldLog(normalizedLevel)) return;
+    const record = {
+      t: new Date().toISOString(),
+      level: normalizedLevel,
+      msg: message,
+      ...fields,
+    };
+    this.stream.write(`${JSON.stringify(record)}\n`);
+  }
+
+  debug(message, fields) {
+    this.write("debug", message, fields);
+  }
+
+  info(message, fields) {
+    this.write("info", message, fields);
+  }
+
+  warn(message, fields) {
+    this.write("warn", message, fields);
+  }
+
+  error(message, fields) {
+    this.write("error", message, fields);
+  }
+
+  attach(eventBus) {
+    if (!eventBus || typeof eventBus.onAny !== "function") return () => {};
+    this.detach();
+    this._unsub = eventBus.onAny(({ event, payload }) => {
+      const level =
+        event === "error"
+          ? "error"
+          : event.startsWith("risk:")
+            ? "warn"
+            : event === "reconnecting" || event === "disconnected"
+              ? "warn"
+              : "info";
+      this.write(level, event, { event, payload });
+    });
+    return () => this.detach();
+  }
+
+  detach() {
+    if (typeof this._unsub === "function") {
+      this._unsub();
+      this._unsub = null;
+    }
+  }
+}
+
+export function createLogger(options) {
+  return new LiveLogger(options);
+}

package/src/live/orchestrator.js

@@ -0,0 +1,133 @@
+import { dayKeyET } from "../engine/execution.js";
+import { EventBus } from "./events.js";
+import { LiveEngine } from "./engine/liveEngine.js";
+
+function asWeight(value) {
+  return Number.isFinite(value) && value > 0 ? value : 0;
+}
+
+function defaultSystemId(system, index) {
+  return system.id || `${system.symbol}-${system.interval || "1m"}-${index + 1}`;
+}
+
+/**
+ * Multi-strategy live orchestrator with portfolio-level guardrails.
+ */
+export class LiveOrchestrator {
+  constructor(options = {}) {
+    if (!Array.isArray(options.systems) || options.systems.length === 0) {
+      throw new Error("orchestrator requires a non-empty systems array");
+    }
+    if (!options.broker) {
+      throw new Error("orchestrator requires a broker adapter");
+    }
+
+    this.options = {
+      allocation: "equal",
+      equity: 10_000,
+      maxDailyLossPct: 0,
+      ...options,
+    };
+    this.eventBus = this.options.eventBus || new EventBus();
+    this.engines = [];
+    this.running = false;
+    this.dayStartEquity = this.options.equity;
+    this.currentDay = null;
+  }
+
+  _emit(event, payload = {}) {
+    this.eventBus.emitEvent(event, payload);
+  }
+
+  _allocationWeights() {
+    const systems = this.options.systems;
+    if (this.options.allocation === "equal") {
+      return systems.map(() => 1);
+    }
+    return systems.map((system) => asWeight(system.weight || 0));
+  }
+
+  _allocatedEquities(totalEquity) {
+    const weights = this._allocationWeights();
+    const totalWeight = weights.reduce((sum, value) => sum + value, 0) || 1;
+    return weights.map((weight) => (totalEquity * weight) / totalWeight);
+  }
+
+  async start() {
+    if (this.running) return;
+    const account = await this.options.broker.getAccount().catch(() => null);
+    const totalEquity = Number.isFinite(account?.equity) ? account.equity : this.options.equity;
+    const perSystemEquity = this._allocatedEquities(totalEquity);
+
+    this.engines = this.options.systems.map((system, index) => {
+      const engineBus = new EventBus();
+      engineBus.onAny(({ event, payload }) => {
+        this._emit(event, {
+          systemId: defaultSystemId(system, index),
+          ...payload,
+        });
+        if (event === "equity:update") this._checkPortfolioLimits();
+      });
+
+      return new LiveEngine({
+        ...system,
+        id: defaultSystemId(system, index),
+        broker: this.options.broker,
+        feed: this.options.feed,
+        storage: this.options.storage,
+        eventBus: engineBus,
+        brokerConfig: this.options.brokerConfig,
+        equity: perSystemEquity[index],
+        useBrokerAccountEquity: false,
+      });
+    });
+
+    await Promise.all(this.engines.map((engine) => engine.start()));
+    this.running = true;
+    this.dayStartEquity = this.getStatus().aggregateEquity;
+    this.currentDay = dayKeyET(Date.now());
+  }
+
+  _checkPortfolioLimits() {
+    if (!this.options.maxDailyLossPct || this.options.maxDailyLossPct <= 0) return;
+    const nowDay = dayKeyET(Date.now());
+    if (this.currentDay !== nowDay) {
+      this.currentDay = nowDay;
+      this.dayStartEquity = this.getStatus().aggregateEquity;
+      return;
+    }
+    const equity = this.getStatus().aggregateEquity;
+    const maxLossFraction = Math.abs(this.options.maxDailyLossPct) / 100;
+    if (equity <= this.dayStartEquity * (1 - maxLossFraction)) {
+      for (const engine of this.engines) {
+        engine.riskManager.halt("portfolio daily loss limit reached");
+      }
+      this._emit("risk:halt", {
+        reason: "portfolio daily loss limit reached",
+        aggregateEquity: equity,
+      });
+    }
+  }
+
+  async stop() {
+    await Promise.all(this.engines.map((engine) => engine.stop()));
+    this.running = false;
+  }
+
+  getStatus() {
+    const systems = this.engines.map((engine) => engine.getStatus());
+    const aggregateEquity = systems.reduce((sum, status) => sum + (status.equity || 0), 0);
+    const openPositions = systems.filter((status) => status.openPosition).length;
+    return {
+      running: this.running,
+      systems,
+      aggregateEquity,
+      openPositions,
+      dayStartEquity: this.dayStartEquity,
+    };
+  }
+}
+
+export function createLiveOrchestrator(options) {
+  return new LiveOrchestrator(options);
+}

package/src/live/storage/interface.js

@@ -0,0 +1,36 @@
+function notImplemented(method) {
+  throw new Error(`StorageProvider.${method}() not implemented`);
+}
+
+/**
+ * Base class for state persistence providers.
+ */
+export class StorageProvider {
+  async load(_namespace) {
+    notImplemented("load");
+  }
+
+  async save(_namespace, _state) {
+    notImplemented("save");
+  }
+
+  async appendTrade(_namespace, _trade) {
+    notImplemented("appendTrade");
+  }
+
+  async appendEquityPoint(_namespace, _point) {
+    notImplemented("appendEquityPoint");
+  }
+
+  async loadTrades(_namespace) {
+    notImplemented("loadTrades");
+  }
+
+  async loadEquityCurve(_namespace) {
+    notImplemented("loadEquityCurve");
+  }
+
+  async clear(_namespace) {
+    notImplemented("clear");
+  }
+}