@tradejs/cli 1.0.9 → 1.0.10

package/dist/lib/binanceMarketContextBackfill.js

@@ -0,0 +1,841 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/lib/binanceMarketContextBackfill.ts
+var binanceMarketContextBackfill_exports = {};
+__export(binanceMarketContextBackfill_exports, {
+  backfillBinanceMarketContextForBacktest: () => backfillBinanceMarketContextForBacktest,
+  backfillBinanceMarketContextForReplay: () => backfillBinanceMarketContextForReplay,
+  backfillBinanceMarketContextForSignals: () => backfillBinanceMarketContextForSignals,
+  buildBreadthBackfillChunks: () => buildBreadthBackfillChunks,
+  buildTradeFlowBackfillChunks: () => buildTradeFlowBackfillChunks,
+  filterMissingBreadthBackfillChunks: () => filterMissingBreadthBackfillChunks,
+  resolveBinanceMarketContextBackfillWindow: () => resolveBinanceMarketContextBackfillWindow,
+  shouldBackfillBinanceMarketContextForBacktest: () => shouldBackfillBinanceMarketContextForBacktest,
+  shouldBackfillBinanceMarketContextForReplay: () => shouldBackfillBinanceMarketContextForReplay,
+  shouldBackfillBinanceMarketContextForSignals: () => shouldBackfillBinanceMarketContextForSignals
+});
+module.exports = __toCommonJS(binanceMarketContextBackfill_exports);
+var import_progress = __toESM(require("progress"));
+var import_chalk = __toESM(require("chalk"));
+var import_connectors = require("@tradejs/connectors");
+var import_connectors2 = require("@tradejs/node/connectors");
+var import_timescale = require("@tradejs/infra/timescale");
+
+// src/lib/binanceMarketData.ts
+var MARKET_FEATURE_INTERVAL_MS = {
+  "1m": 6e4,
+  "5m": 3e5,
+  "15m": 9e5,
+  "1h": 36e5
+};
+var STABLE_QUOTE_SYMBOLS = /* @__PURE__ */ new Set([
+  "USDCUSDT",
+  "FDUSDUSDT",
+  "TUSDUSDT",
+  "BUSDUSDT",
+  "USDPUSDT",
+  "DAIUSDT"
+]);
+var safeDivide = (num, den) => Number.isFinite(num) && Number.isFinite(den) && den !== 0 ? num / den : null;
+var mean = (values) => values.length ? values.reduce((sum, value) => sum + value, 0) / values.length : null;
+var standardDeviation = (values) => {
+  const avg = mean(values);
+  if (avg == null || values.length < 2) return null;
+  const variance = values.reduce((sum, value) => sum + (value - avg) ** 2, 0) / values.length;
+  return Math.sqrt(variance);
+};
+var buildPrefixSum = (values) => {
+  const prefix = [0];
+  for (const value of values) prefix.push(prefix[prefix.length - 1] + value);
+  return prefix;
+};
+var sumPrefixRange = (prefix, startIndex, endIndexInclusive) => {
+  if (endIndexInclusive < startIndex) return 0;
+  const start = Math.max(0, startIndex);
+  const end = Math.min(prefix.length - 2, endIndexInclusive);
+  if (end < start) return 0;
+  return prefix[end + 1] - prefix[start];
+};
+var windowReturn = (candles, index, lookbackBars) => {
+  const previous = candles[index - lookbackBars];
+  const current = candles[index];
+  return previous && previous.close > 0 ? (current.close - previous.close) / previous.close : null;
+};
+var classifyBtcAltRegime = ({
+  btcReturn24h,
+  altBasketReturn24h,
+  btcVsAltReturn24h
+}) => {
+  if (btcReturn24h == null || altBasketReturn24h == null || btcVsAltReturn24h == null) {
+    return "unknown";
+  }
+  if (btcReturn24h < -0.015 && altBasketReturn24h < -0.025) {
+    return "risk_off";
+  }
+  if (btcReturn24h > 5e-3 && altBasketReturn24h > 5e-3 && altBasketReturn24h > btcReturn24h) {
+    return "risk_on";
+  }
+  if (btcVsAltReturn24h > 5e-3) return "btc_lead";
+  if (btcVsAltReturn24h < -5e-3) return "alt_lead";
+  return "neutral";
+};
+var selectBreadthUniverseFromTickers = (tickers, limit) => tickers.filter(
+  (ticker) => ticker.symbol.endsWith("USDT") && ticker.symbol !== "BTCUSDT" && !STABLE_QUOTE_SYMBOLS.has(ticker.symbol) && Number.isFinite(ticker.turnover24h) && ticker.turnover24h > 0
+).sort((a, b) => b.turnover24h - a.turnover24h).slice(0, Math.max(0, limit)).map((ticker) => ticker.symbol);
+var aggregateAggTradesToRows = ({
+  symbol,
+  interval,
+  trades,
+  source = "binance_agg_trades"
+}) => {
+  const intervalMs = MARKET_FEATURE_INTERVAL_MS[interval];
+  const buckets = /* @__PURE__ */ new Map();
+  for (const trade of trades) {
+    const bucketTs = Math.floor(trade.timestamp / intervalMs) * intervalMs;
+    const row = buckets.get(bucketTs) ?? {
+      symbol,
+      interval,
+      ts: new Date(bucketTs),
+      trades: 0,
+      buyBaseVolume: 0,
+      sellBaseVolume: 0,
+      buyQuoteVolume: 0,
+      sellQuoteVolume: 0,
+      netBaseDelta: 0,
+      netQuoteDelta: 0,
+      buyPressurePct: null,
+      source
+    };
+    const quote = trade.price * trade.quantity;
+    const isAggressiveSell = trade.isBuyerMaker;
+    row.trades += 1;
+    if (isAggressiveSell) {
+      row.sellBaseVolume = (row.sellBaseVolume ?? 0) + trade.quantity;
+      row.sellQuoteVolume = (row.sellQuoteVolume ?? 0) + quote;
+    } else {
+      row.buyBaseVolume = (row.buyBaseVolume ?? 0) + trade.quantity;
+      row.buyQuoteVolume = (row.buyQuoteVolume ?? 0) + quote;
+    }
+    row.netBaseDelta = (row.buyBaseVolume ?? 0) - (row.sellBaseVolume ?? 0);
+    row.netQuoteDelta = (row.buyQuoteVolume ?? 0) - (row.sellQuoteVolume ?? 0);
+    row.buyPressurePct = safeDivide(
+      row.buyBaseVolume ?? 0,
+      (row.buyBaseVolume ?? 0) + (row.sellBaseVolume ?? 0)
+    );
+    buckets.set(bucketTs, row);
+  }
+  return [...buckets.values()].sort((a, b) => a.ts.getTime() - b.ts.getTime());
+};
+var buildKlineTradeFlowRows = ({
+  symbol,
+  interval,
+  candles,
+  source = "binance_klines"
+}) => candles.map((candle) => {
+  const buyBaseVolume = candle.takerBuyBaseVolume;
+  const buyQuoteVolume = candle.takerBuyQuoteVolume;
+  if (buyBaseVolume == null || buyQuoteVolume == null || !Number.isFinite(buyBaseVolume) || !Number.isFinite(buyQuoteVolume)) {
+    return null;
+  }
+  const sellBaseVolume = candle.takerSellBaseVolume != null && Number.isFinite(candle.takerSellBaseVolume) ? candle.takerSellBaseVolume : Math.max(0, candle.volume - buyBaseVolume);
+  const sellQuoteVolume = candle.takerSellQuoteVolume != null && Number.isFinite(candle.takerSellQuoteVolume) ? candle.takerSellQuoteVolume : Math.max(0, candle.turnover - buyQuoteVolume);
+  const trades = candle.trades != null && Number.isFinite(candle.trades) ? Math.max(0, Math.trunc(candle.trades)) : 0;
+  return {
+    symbol,
+    interval,
+    ts: new Date(candle.timestamp),
+    trades,
+    buyBaseVolume,
+    sellBaseVolume,
+    buyQuoteVolume,
+    sellQuoteVolume,
+    netBaseDelta: buyBaseVolume - sellBaseVolume,
+    netQuoteDelta: buyQuoteVolume - sellQuoteVolume,
+    buyPressurePct: safeDivide(
+      buyBaseVolume,
+      buyBaseVolume + sellBaseVolume
+    ),
+    source
+  };
+}).filter((row) => row != null);
+var buildMarketBreadthRows = ({
+  universe,
+  interval,
+  candlesBySymbol,
+  btcCandles,
+  source = "binance_klines"
+}) => {
+  const timestamps = /* @__PURE__ */ new Set();
+  const indexedSymbols = Object.values(candlesBySymbol).map((candles) => ({
+    candles,
+    byTimestamp: new Map(
+      candles.map((candle, index) => [candle.timestamp, index])
+    ),
+    turnoverPrefix: buildPrefixSum(
+      candles.map((candle) => Math.max(0, candle.turnover ?? 0))
+    ),
+    closePrefix: buildPrefixSum(candles.map((candle) => candle.close))
+  }));
+  const btcIndexed = btcCandles ? {
+    candles: btcCandles,
+    byTimestamp: new Map(
+      btcCandles.map((candle, index) => [candle.timestamp, index])
+    ),
+    turnoverPrefix: buildPrefixSum(
+      btcCandles.map((candle) => Math.max(0, candle.turnover ?? 0))
+    )
+  } : null;
+  const intervalMs = MARKET_FEATURE_INTERVAL_MS[interval];
+  const bars1h = Math.max(1, Math.round(36e5 / intervalMs));
+  const bars4h = Math.max(1, Math.round(144e5 / intervalMs));
+  const bars24h = Math.max(1, Math.round(864e5 / intervalMs));
+  for (const candles of Object.values(candlesBySymbol)) {
+    for (const candle of candles) timestamps.add(candle.timestamp);
+  }
+  return [...timestamps].sort((a, b) => a - b).map((timestamp) => {
+    const returns = [];
+    const weightedReturns = [];
+    let advancers = 0;
+    let decliners = 0;
+    let unchanged = 0;
+    let aboveMa20 = 0;
+    let aboveMa20Eligible = 0;
+    let aboveMa50 = 0;
+    let aboveMa50Eligible = 0;
+    const altReturns1h = [];
+    const altReturns4h = [];
+    const altReturns24h = [];
+    let altTurnover1h = 0;
+    let altTurnover24h = 0;
+    let previousAltTurnover24h = 0;
+    for (const indexed of indexedSymbols) {
+      const { candles, byTimestamp, turnoverPrefix, closePrefix } = indexed;
+      const index = byTimestamp.get(timestamp);
+      if (index == null) continue;
+      const candle = candles[index];
+      const previous = candles[index - 1];
+      const ret = previous && previous.close > 0 ? (candle.close - previous.close) / previous.close : 0;
+      if (ret > 0) advancers += 1;
+      else if (ret < 0) decliners += 1;
+      else unchanged += 1;
+      returns.push(ret);
+      weightedReturns.push({
+        value: ret,
+        weight: Math.max(0, candle.turnover ?? 0)
+      });
+      const ma20Start = index - 19;
+      if (ma20Start >= 0) {
+        aboveMa20Eligible += 1;
+        const ma20 = sumPrefixRange(closePrefix, ma20Start, index) / 20;
+        if (candle.close > ma20) aboveMa20 += 1;
+      }
+      const ma50Start = index - 49;
+      if (ma50Start >= 0) {
+        aboveMa50Eligible += 1;
+        const ma50 = sumPrefixRange(closePrefix, ma50Start, index) / 50;
+        if (candle.close > ma50) aboveMa50 += 1;
+      }
+      const altReturn1h = windowReturn(candles, index, bars1h);
+      const altReturn4h = windowReturn(candles, index, bars4h);
+      const altReturn24h = windowReturn(candles, index, bars24h);
+      if (altReturn1h != null) altReturns1h.push(altReturn1h);
+      if (altReturn4h != null) altReturns4h.push(altReturn4h);
+      if (altReturn24h != null) altReturns24h.push(altReturn24h);
+      altTurnover1h += sumPrefixRange(
+        turnoverPrefix,
+        index - bars1h + 1,
+        index
+      );
+      altTurnover24h += sumPrefixRange(
+        turnoverPrefix,
+        index - bars24h + 1,
+        index
+      );
+      previousAltTurnover24h += sumPrefixRange(
+        turnoverPrefix,
+        index - bars24h * 2 + 1,
+        index - bars24h
+      );
+    }
+    const weightSum = weightedReturns.reduce(
+      (sum, item) => sum + item.weight,
+      0
+    );
+    const volumeWeightedReturn = weightSum > 0 ? weightedReturns.reduce(
+      (sum, item) => sum + item.value * item.weight,
+      0
+    ) / weightSum : null;
+    const btcIndex = btcIndexed?.byTimestamp.get(timestamp);
+    const btcReturn1h = btcIndexed && btcIndex != null ? windowReturn(btcIndexed.candles, btcIndex, bars1h) : null;
+    const btcReturn4h = btcIndexed && btcIndex != null ? windowReturn(btcIndexed.candles, btcIndex, bars4h) : null;
+    const btcReturn24h = btcIndexed && btcIndex != null ? windowReturn(btcIndexed.candles, btcIndex, bars24h) : null;
+    const btcTurnover1h = btcIndexed && btcIndex != null ? sumPrefixRange(
+      btcIndexed.turnoverPrefix,
+      btcIndex - bars1h + 1,
+      btcIndex
+    ) : null;
+    const btcTurnover24h = btcIndexed && btcIndex != null ? sumPrefixRange(
+      btcIndexed.turnoverPrefix,
+      btcIndex - bars24h + 1,
+      btcIndex
+    ) : null;
+    const previousBtcTurnover24h = btcIndexed && btcIndex != null ? sumPrefixRange(
+      btcIndexed.turnoverPrefix,
+      btcIndex - bars24h * 2 + 1,
+      btcIndex - bars24h
+    ) : null;
+    const altBasketReturn1h = mean(altReturns1h);
+    const altBasketReturn4h = mean(altReturns4h);
+    const altBasketReturn24h = mean(altReturns24h);
+    const btcVsAltReturn1h = btcReturn1h == null || altBasketReturn1h == null ? null : btcReturn1h - altBasketReturn1h;
+    const btcVsAltReturn4h = btcReturn4h == null || altBasketReturn4h == null ? null : btcReturn4h - altBasketReturn4h;
+    const btcVsAltReturn24h = btcReturn24h == null || altBasketReturn24h == null ? null : btcReturn24h - altBasketReturn24h;
+    const btcTurnoverShare1h = btcTurnover1h == null ? null : safeDivide(btcTurnover1h, btcTurnover1h + altTurnover1h);
+    const btcTurnoverShare24h = btcTurnover24h == null ? null : safeDivide(btcTurnover24h, btcTurnover24h + altTurnover24h);
+    const previousBtcTurnoverShare24h = previousBtcTurnover24h == null ? null : safeDivide(
+      previousBtcTurnover24h,
+      previousBtcTurnover24h + previousAltTurnover24h
+    );
+    const btcTurnoverShareChange24h = btcTurnoverShare24h == null || previousBtcTurnoverShare24h == null ? null : btcTurnoverShare24h - previousBtcTurnoverShare24h;
+    return {
+      universe,
+      interval,
+      ts: new Date(timestamp),
+      symbolsCount: returns.length,
+      advancers,
+      decliners,
+      unchanged,
+      advanceDeclineRatio: safeDivide(advancers, decliners || 1),
+      pctAboveMa20: safeDivide(aboveMa20, aboveMa20Eligible),
+      pctAboveMa50: safeDivide(aboveMa50, aboveMa50Eligible),
+      equalWeightedReturn: mean(returns),
+      volumeWeightedReturn,
+      dispersion: standardDeviation(returns),
+      btcReturn1h,
+      btcReturn4h,
+      btcReturn24h,
+      altBasketReturn1h,
+      altBasketReturn4h,
+      altBasketReturn24h,
+      btcVsAltReturn1h,
+      btcVsAltReturn4h,
+      btcVsAltReturn24h,
+      btcTurnoverShare1h,
+      btcTurnoverShare24h,
+      btcTurnoverShareChange24h,
+      altVolToBtcVol24h: btcTurnover24h == null ? null : safeDivide(altTurnover24h, btcTurnover24h),
+      altDispersion24h: standardDeviation(altReturns24h),
+      btcAltRegime: classifyBtcAltRegime({
+        btcReturn24h,
+        altBasketReturn24h,
+        btcVsAltReturn24h
+      }),
+      source
+    };
+  }).filter((row) => row.symbolsCount > 0);
+};
+
+// src/lib/binanceMarketContextBackfill.ts
+var DAY_MS = 864e5;
+var sleep = (ms) => ms > 0 ? new Promise((resolve) => setTimeout(resolve, ms)) : Promise.resolve();
+var asInt = (value, fallback) => {
+  const parsed = Number.parseInt(String(value ?? ""), 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+};
+var asFloat = (value, fallback) => {
+  const parsed = Number.parseFloat(String(value ?? ""));
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+};
+var parseEnabledFlag = (value, defaultValue) => {
+  const normalized = String(value ?? "").trim().toLowerCase();
+  if (!normalized) return defaultValue;
+  if (["1", "true", "yes", "on"].includes(normalized)) return true;
+  if (["0", "false", "no", "off"].includes(normalized)) return false;
+  return defaultValue;
+};
+var uniqueSymbols = (symbols) => [
+  ...new Set(symbols.map((item) => item.trim().toUpperCase()).filter(Boolean))
+];
+var getReferenceSymbols = () => {
+  const symbols = (process.env.BINANCE_MARKET_CONTEXT_REFERENCE_SYMBOLS || "BTCUSDT,ETHUSDT").split(",").map((item) => item.trim().toUpperCase()).filter(Boolean);
+  return symbols.length ? [...new Set(symbols)] : ["BTCUSDT", "ETHUSDT"];
+};
+var intervalToMarketFeatureInterval = (interval) => {
+  const normalized = String(interval).trim().toLowerCase();
+  if (normalized === "1" || normalized === "1m") return "1m";
+  if (normalized === "5" || normalized === "5m") return "5m";
+  if (normalized === "60" || normalized === "1h") return "1h";
+  return "15m";
+};
+var marketIntervalToConnectorInterval = (interval) => {
+  if (interval === "1m") return "1";
+  if (interval === "5m") return "5";
+  if (interval === "1h") return "60";
+  return "15";
+};
+var resolveBinanceMarketContextBackfillWindow = ({
+  startMs,
+  endMs,
+  preloadStartMs
+}) => {
+  const breadthLookbackDays = asFloat(
+    process.env.BINANCE_MARKET_CONTEXT_BREADTH_BACKFILL_LOOKBACK_DAYS,
+    3
+  );
+  const breadthWarmupStartMs = startMs - breadthLookbackDays * DAY_MS;
+  return {
+    breadthStartMs: preloadStartMs ?? breadthWarmupStartMs,
+    tradeFlowStartMs: preloadStartMs ?? startMs,
+    endMs
+  };
+};
+var hasCoverage = ({
+  coverage,
+  startMs,
+  endMs,
+  intervalMs
+}) => {
+  if (!coverage) return false;
+  const expectedRows = Math.max(1, Math.floor((endMs - startMs) / intervalMs));
+  return coverage.firstMs <= startMs + intervalMs && coverage.lastMs >= endMs - intervalMs && coverage.rows >= Math.floor(expectedRows * 0.9);
+};
+var buildBreadthBackfillChunks = ({
+  startMs,
+  endMs,
+  intervalMs,
+  chunkDays
+}) => {
+  const chunkMs = Math.max(intervalMs, chunkDays * DAY_MS);
+  const warmupBars = Math.max(50, Math.ceil(DAY_MS * 2 / intervalMs));
+  const warmupMs = warmupBars * intervalMs;
+  const chunks = [];
+  let cursor = startMs;
+  while (cursor <= endMs) {
+    const chunkEndMs = Math.min(endMs, cursor + chunkMs - 1);
+    chunks.push({
+      startMs: cursor,
+      endMs: chunkEndMs,
+      fetchStartMs: Math.max(startMs, cursor - warmupMs)
+    });
+    cursor = chunkEndMs + 1;
+  }
+  return chunks;
+};
+var buildTradeFlowBackfillChunks = ({
+  startMs,
+  endMs,
+  intervalMs,
+  chunkDays
+}) => {
+  const chunkMs = Math.max(intervalMs, chunkDays * DAY_MS);
+  const chunks = [];
+  let cursor = startMs;
+  while (cursor <= endMs) {
+    const chunkEndMs = Math.min(endMs, cursor + chunkMs - 1);
+    chunks.push({ startMs: cursor, endMs: chunkEndMs });
+    cursor = chunkEndMs + 1;
+  }
+  return chunks;
+};
+var filterMissingBreadthBackfillChunks = ({
+  chunks,
+  coverage,
+  intervalMs
+}) => chunks.filter(
+  (chunk) => !hasCoverage({
+    coverage,
+    startMs: chunk.startMs,
+    endMs: chunk.endMs,
+    intervalMs
+  })
+);
+var fetchAggTradesForWindow = async ({
+  connector,
+  symbol,
+  fromMs,
+  toMs,
+  batchMinutes,
+  requestDelayMs
+}) => {
+  if (!connector.getAggTrades) return [];
+  const rows = [];
+  const batchMs = Math.max(1, batchMinutes) * 6e4;
+  let cursor = fromMs;
+  while (cursor <= toMs) {
+    const endTime = Math.min(toMs, cursor + batchMs - 1);
+    let pageCursor = cursor;
+    while (pageCursor <= endTime) {
+      const page = await connector.getAggTrades({
+        symbol,
+        startTime: pageCursor,
+        endTime,
+        limit: 1e3
+      });
+      if (!page.length) break;
+      rows.push(...page);
+      const lastTs = page[page.length - 1]?.timestamp;
+      if (page.length < 1e3 || !Number.isFinite(lastTs)) break;
+      const nextCursor = Math.max(pageCursor + 1, Number(lastTs) + 1);
+      if (nextCursor > endTime) break;
+      pageCursor = nextCursor;
+      await sleep(requestDelayMs);
+    }
+    cursor = endTime + 1;
+    await sleep(requestDelayMs);
+  }
+  return rows;
+};
+var getBinanceConnector = async ({
+  projectRoot,
+  userName
+}) => {
+  const creator = await (0, import_connectors2.getConnectorCreatorByName)(
+    import_connectors.ConnectorNames.Binance,
+    projectRoot
+  );
+  if (!creator) {
+    throw new Error(
+      "Binance connector is required for market context backfill"
+    );
+  }
+  return creator({ userName });
+};
+var shouldBackfillBinanceMarketContextForBacktest = ({
+  aiEnabled,
+  cacheOnly,
+  mlEnabled
+}) => parseEnabledFlag(
+  process.env.BINANCE_MARKET_CONTEXT_BACKFILL_ENABLED,
+  (aiEnabled || mlEnabled) && !cacheOnly
+);
+var shouldBackfillBinanceMarketContextForSignals = ({
+  cacheOnly
+}) => parseEnabledFlag(
+  process.env.BINANCE_MARKET_CONTEXT_BACKFILL_ENABLED,
+  !cacheOnly
+);
+var shouldBackfillBinanceMarketContextForReplay = ({
+  cacheOnly
+}) => parseEnabledFlag(
+  process.env.BINANCE_MARKET_CONTEXT_BACKFILL_ENABLED,
+  !cacheOnly
+);
+var skippedBackfillResult = () => ({
+  skipped: true,
+  tradeFlowRows: 0,
+  depthRows: 0,
+  breadthRows: 0,
+  skippedSymbols: 0
+});
+var backfillBinanceMarketContext = async (params, enabled) => {
+  const symbols = uniqueSymbols(params.symbols);
+  if (!enabled || !symbols.length) {
+    return skippedBackfillResult();
+  }
+  const interval = intervalToMarketFeatureInterval(params.interval);
+  const intervalMs = MARKET_FEATURE_INTERVAL_MS[interval];
+  const { breadthStartMs, tradeFlowStartMs, endMs } = resolveBinanceMarketContextBackfillWindow(params);
+  if (endMs <= Math.min(breadthStartMs, tradeFlowStartMs)) {
+    return skippedBackfillResult();
+  }
+  await (0, import_timescale.waitForDbReady)();
+  const connector = await getBinanceConnector({
+    projectRoot: params.projectRoot,
+    userName: params.userName
+  });
+  const includeTradeFlow = parseEnabledFlag(
+    process.env.BINANCE_MARKET_CONTEXT_BACKFILL_TRADE_FLOW,
+    true
+  );
+  const includeBreadth = parseEnabledFlag(
+    process.env.BINANCE_MARKET_CONTEXT_BACKFILL_BREADTH,
+    true
+  );
+  const requestDelayMs = asInt(
+    process.env.BINANCE_MARKET_CONTEXT_BACKFILL_REQUEST_DELAY_MS,
+    75
+  );
+  const batchMinutes = asInt(
+    process.env.BINANCE_MARKET_CONTEXT_BACKFILL_BATCH_MINUTES,
+    60
+  );
+  const symbolLimit = asInt(
+    process.env.BINANCE_MARKET_CONTEXT_TRADE_FLOW_SYMBOL_LIMIT,
+    2
+  );
+  const breadthLimit = asInt(
+    process.env.BINANCE_MARKET_CONTEXT_BREADTH_LIMIT,
+    30
+  );
+  const breadthChunkDays = asFloat(
+    process.env.BINANCE_MARKET_CONTEXT_BREADTH_CHUNK_DAYS,
+    30
+  );
+  const tradeFlowChunkDays = asFloat(
+    process.env.BINANCE_MARKET_CONTEXT_TRADE_FLOW_CHUNK_DAYS,
+    30
+  );
+  const tradeFlowSource = String(
+    process.env.BINANCE_MARKET_CONTEXT_TRADE_FLOW_SOURCE || "klines"
+  ).trim().toLowerCase();
+  const referenceSymbols = getReferenceSymbols().slice(0, symbolLimit);
+  const skippedSymbols = Math.max(0, symbols.length - referenceSymbols.length);
+  let tradeFlowRows = 0;
+  let breadthRows = 0;
+  console.log(
+    import_chalk.default.cyan(
+      `binance market context backfill: requestedSymbols=${symbols.length}, referenceSymbols=${referenceSymbols.length}, interval=${interval}, tradeFlowWindow=${new Date(tradeFlowStartMs).toISOString()}..${new Date(endMs).toISOString()}, breadthWindow=${new Date(breadthStartMs).toISOString()}..${new Date(endMs).toISOString()}`
+    )
+  );
+  if (includeTradeFlow && referenceSymbols.length) {
+    const coverage = await (0, import_timescale.getMarketTradeFlowCoverage)({
+      symbols: referenceSymbols,
+      interval,
+      startMs: tradeFlowStartMs,
+      endMs
+    });
+    const missingSymbols = referenceSymbols.filter(
+      (symbol) => !hasCoverage({
+        coverage: coverage.get(symbol),
+        startMs: tradeFlowStartMs,
+        endMs,
+        intervalMs
+      })
+    );
+    const bar = new import_progress.default(
+      "tradeFlow :current/:total [:bar][:percent] :etas(s) rows=:rows skip=:skip :symbol",
+      {
+        total: Math.max(1, missingSymbols.length),
+        width: 24
+      }
+    );
+    if (!missingSymbols.length) {
+      bar.tick(1, { rows: 0, skip: referenceSymbols.length, symbol: "cached" });
+    }
+    const connectorInterval = marketIntervalToConnectorInterval(interval);
+    const chunks = buildTradeFlowBackfillChunks({
+      startMs: tradeFlowStartMs,
+      endMs,
+      intervalMs,
+      chunkDays: tradeFlowChunkDays
+    });
+    const chunkBar = missingSymbols.length ? new import_progress.default(
+      "tradeFlow chunks :current/:total [:bar][:percent] :etas(s) rows=:rows skip=:skip chunk=:chunk :symbol",
+      {
+        total: Math.max(1, chunks.length * missingSymbols.length),
+        width: 24
+      }
+    ) : null;
+    let skippedTradeFlowChunks = 0;
+    for (const symbol of missingSymbols) {
+      const symbolCoverage = coverage.get(symbol);
+      for (let chunkIndex = 0; chunkIndex < chunks.length; chunkIndex += 1) {
+        const chunk = chunks[chunkIndex];
+        if (hasCoverage({
+          coverage: symbolCoverage,
+          startMs: chunk.startMs,
+          endMs: chunk.endMs,
+          intervalMs
+        })) {
+          skippedTradeFlowChunks += 1;
+          chunkBar?.tick(1, {
+            rows: tradeFlowRows,
+            skip: skippedTradeFlowChunks,
+            chunk: `${chunkIndex + 1}/${chunks.length}`,
+            symbol
+          });
+          continue;
+        }
+        const rows = tradeFlowSource === "agg_trades" ? aggregateAggTradesToRows({
+          symbol,
+          interval,
+          trades: await fetchAggTradesForWindow({
+            connector,
+            symbol,
+            fromMs: chunk.startMs,
+            toMs: chunk.endMs,
+            batchMinutes,
+            requestDelayMs
+          })
+        }) : buildKlineTradeFlowRows({
+          symbol,
+          interval,
+          candles: await connector.kline({
+            symbol,
+            interval: connectorInterval,
+            start: chunk.startMs,
+            end: chunk.endMs,
+            silent: true
+          })
+        });
+        const boundedRows = rows.filter((row) => {
+          const ts = row.ts.getTime();
+          return ts >= chunk.startMs && ts <= chunk.endMs;
+        });
+        await (0, import_timescale.upsertMarketTradeFlowRows)(boundedRows);
+        tradeFlowRows += boundedRows.length;
+        chunkBar?.tick(1, {
+          rows: tradeFlowRows,
+          skip: skippedTradeFlowChunks,
+          chunk: `${chunkIndex + 1}/${chunks.length}`,
+          symbol
+        });
+      }
+      bar.tick(1, {
+        rows: tradeFlowRows,
+        skip: referenceSymbols.length - missingSymbols.length + skippedSymbols,
+        symbol
+      });
+    }
+  }
+  if (includeBreadth) {
+    const tickers = await connector.getTickers();
+    const breadthSymbols = selectBreadthUniverseFromTickers(
+      tickers,
+      breadthLimit
+    );
+    const universe = `binance_top${breadthSymbols.length}_usdt`;
+    const coverage = await (0, import_timescale.getMarketBreadthCoverage)({
+      universe,
+      interval,
+      startMs: breadthStartMs,
+      endMs
+    });
+    const hasBtcAltMetrics = (coverage?.btcAltMetricsRows ?? 0) >= Math.floor(Math.max(1, coverage?.rows ?? 0) * 0.9);
+    if (!hasCoverage({
+      coverage,
+      startMs: breadthStartMs,
+      endMs,
+      intervalMs
+    }) || !hasBtcAltMetrics) {
+      const connectorInterval = marketIntervalToConnectorInterval(interval);
+      const chunks = buildBreadthBackfillChunks({
+        startMs: breadthStartMs,
+        endMs,
+        intervalMs,
+        chunkDays: breadthChunkDays
+      });
+      const missingChunks = filterMissingBreadthBackfillChunks({
+        chunks,
+        coverage,
+        intervalMs
+      });
+      const bar = new import_progress.default(
+        "breadth :current/:total [:bar][:percent] :etas(s) candles=:candles skip=:skip chunk=:chunk :symbol",
+        {
+          total: Math.max(1, missingChunks.length * breadthSymbols.length),
+          width: 24
+        }
+      );
+      let candlesRead = 0;
+      let skippedBreadthChunks = chunks.length - missingChunks.length;
+      if (!missingChunks.length) {
+        bar.tick(1, {
+          candles: 0,
+          skip: skippedBreadthChunks,
+          chunk: "cached",
+          symbol: universe
+        });
+      }
+      for (let chunkIndex = 0; chunkIndex < missingChunks.length; chunkIndex += 1) {
+        const chunk = missingChunks[chunkIndex];
+        const originalChunkIndex = chunks.findIndex(
+          (item) => item.startMs === chunk.startMs && item.endMs === chunk.endMs
+        );
+        const candlesBySymbol = {};
+        for (const symbol of breadthSymbols) {
+          const candles = await connector.kline({
+            symbol,
+            interval: connectorInterval,
+            start: chunk.fetchStartMs,
+            end: chunk.endMs,
+            silent: true
+          });
+          candlesBySymbol[symbol] = candles;
+          candlesRead += candles.length;
+          bar.tick(1, {
+            candles: candlesRead,
+            skip: skippedBreadthChunks,
+            chunk: `${originalChunkIndex + 1}/${chunks.length}`,
+            symbol
+          });
+        }
+        const btcCandles = await connector.kline({
+          symbol: "BTCUSDT",
+          interval: connectorInterval,
+          start: chunk.fetchStartMs,
+          end: chunk.endMs,
+          silent: true
+        });
+        const rows = buildMarketBreadthRows({
+          universe,
+          interval,
+          candlesBySymbol,
+          btcCandles
+        }).filter((row) => {
+          const ts = row.ts.getTime();
+          return ts >= chunk.startMs && ts <= chunk.endMs;
+        });
+        await (0, import_timescale.upsertMarketBreadthRows)(rows);
+        breadthRows += rows.length;
+      }
+    } else {
+      console.log(import_chalk.default.gray(`breadth cached: universe=${universe}`));
+    }
+  }
+  console.log(
+    import_chalk.default.green(
+      `binance market context backfill done: tradeFlowRows=${tradeFlowRows}, depthRows=0, breadthRows=${breadthRows}, skippedSymbols=${skippedSymbols}`
+    )
+  );
+  return {
+    skipped: false,
+    tradeFlowRows,
+    depthRows: 0,
+    breadthRows,
+    skippedSymbols
+  };
+};
+var backfillBinanceMarketContextForBacktest = (params) => backfillBinanceMarketContext(params, true);
+var backfillBinanceMarketContextForSignals = (params) => backfillBinanceMarketContext(params, true);
+var backfillBinanceMarketContextForReplay = (params) => backfillBinanceMarketContext(params, true);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  backfillBinanceMarketContextForBacktest,
+  backfillBinanceMarketContextForReplay,
+  backfillBinanceMarketContextForSignals,
+  buildBreadthBackfillChunks,
+  buildTradeFlowBackfillChunks,
+  filterMissingBreadthBackfillChunks,
+  resolveBinanceMarketContextBackfillWindow,
+  shouldBackfillBinanceMarketContextForBacktest,
+  shouldBackfillBinanceMarketContextForReplay,
+  shouldBackfillBinanceMarketContextForSignals
+});