@tradejs/infra 2.0.17 → 2.0.19

package/dist/timescale/derivatives.js

@@ -0,0 +1,1270 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+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 __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/timescale/derivatives.ts
+var derivatives_exports = {};
+__export(derivatives_exports, {
+  applyDerivativesMetricCoverage: () => applyDerivativesMetricCoverage,
+  ensureDerivativesSchema: () => ensureDerivativesSchema,
+  getDerivativesBackfillCoverage: () => getDerivativesBackfillCoverage,
+  getDerivativesDataEdgesForSymbols: () => getDerivativesDataEdgesForSymbols,
+  getDerivativesMetricCoverage: () => getDerivativesMetricCoverage,
+  getDerivativesRangeForSymbols: () => getDerivativesRangeForSymbols,
+  getDerivativesSummary: () => getDerivativesSummary,
+  getDerivativesWindow: () => getDerivativesWindow,
+  upsertDerivatives: () => upsertDerivatives,
+  upsertDerivativesBackfillCoverage: () => upsertDerivativesBackfillCoverage
+});
+module.exports = __toCommonJS(derivatives_exports);
+
+// src/timescale/pool.ts
+var import_pg = require("pg");
+var getPool = () => {
+  if (!global.__pgPool__) {
+    const max = Number(process.env.PG_POOL_MAX ?? 10);
+    const connectionTimeoutMillis = Number(
+      process.env.PG_CONNECTION_TIMEOUT_MS ?? 3e4
+    );
+    global.__pgPool__ = new import_pg.Pool({
+      host: process.env.PG_HOST || "127.0.0.1",
+      port: Number(process.env.PG_PORT ?? 5432),
+      user: process.env.PG_USER || "app",
+      password: String(process.env.PG_PASSWORD ?? "app"),
+      database: process.env.PG_DATABASE || process.env.PG_DB || "app",
+      max: Number.isFinite(max) && max > 0 ? Math.floor(max) : 10,
+      idleTimeoutMillis: 3e4,
+      connectionTimeoutMillis: Number.isFinite(connectionTimeoutMillis) && connectionTimeoutMillis > 0 ? Math.floor(connectionTimeoutMillis) : 3e4
+    });
+  }
+  return global.__pgPool__;
+};
+
+// src/timescale/query.ts
+var resolveQueryTimeoutMs = (override) => {
+  if (Number.isFinite(override) && Number(override) > 0) {
+    return Math.floor(Number(override));
+  }
+  const configured = Number(process.env.MARKET_CONTEXT_SQL_TIMEOUT_MS);
+  return Number.isFinite(configured) && configured > 0 ? Math.floor(configured) : 3e4;
+};
+var createQueryError = (name, message) => {
+  const error = new Error(message);
+  error.name = name;
+  return error;
+};
+var queryMarketContext = async (text, values, options = {}) => {
+  const client = await getPool().connect();
+  const timeoutMs = resolveQueryTimeoutMs(options.timeoutMs);
+  let released = false;
+  let rejectCancellation;
+  const release = (error) => {
+    if (released) return;
+    released = true;
+    client.release(error);
+  };
+  const cancellation = new Promise((_resolve, reject) => {
+    rejectCancellation = reject;
+  });
+  const cancel = (error) => {
+    release(error);
+    rejectCancellation?.(error);
+  };
+  const onAbort = () => cancel(
+    createQueryError("AbortError", "Timescale market-context query aborted")
+  );
+  const timer = setTimeout(
+    () => cancel(
+      createQueryError(
+        "TimescaleQueryTimeoutError",
+        `Timescale market-context query exceeded ${timeoutMs}ms`
+      )
+    ),
+    timeoutMs
+  );
+  timer.unref?.();
+  options.signal?.addEventListener("abort", onAbort, { once: true });
+  try {
+    if (options.signal?.aborted) {
+      const error = createQueryError(
+        "AbortError",
+        "Timescale market-context query aborted"
+      );
+      release(error);
+      throw error;
+    }
+    return await Promise.race([client.query(text, values), cancellation]);
+  } finally {
+    clearTimeout(timer);
+    options.signal?.removeEventListener("abort", onAbort);
+    release();
+  }
+};
+
+// src/timescale/values.ts
+var normalizeCandleSymbol = (symbol) => String(symbol || "").trim().toUpperCase();
+
+// src/timescale/internal.ts
+var derivativesSchemaReady = false;
+var binanceMarketSchemaReady = false;
+var hyperliquidWhaleSchemaReady = false;
+var derivativesSchemaReadyPromise = null;
+var binanceMarketSchemaReadyPromise = null;
+var hyperliquidWhaleSchemaReadyPromise = null;
+var marketContextSchemaMode = "ensure";
+var verifiedMarketContextSchemas = /* @__PURE__ */ new Set();
+var DERIVATIVES_SCHEMA_LOCK_KEY = 610001;
+var BINANCE_MARKET_SCHEMA_LOCK_KEY = 610003;
+var HYPERLIQUID_WHALE_SCHEMA_LOCK_KEY = 610004;
+var withSchemaLock = async (lockKey, work) => {
+  const pool = getPool();
+  await pool.query("SELECT pg_advisory_lock($1)", [lockKey]);
+  try {
+    await work();
+  } finally {
+    await pool.query("SELECT pg_advisory_unlock($1)", [lockKey]);
+  }
+};
+var ensureDerivativesSchema = async () => {
+  if (derivativesSchemaReady) return;
+  if (derivativesSchemaReadyPromise) {
+    await derivativesSchemaReadyPromise;
+    return;
+  }
+  const pool = getPool();
+  derivativesSchemaReadyPromise = withSchemaLock(
+    DERIVATIVES_SCHEMA_LOCK_KEY,
+    async () => {
+      if (derivativesSchemaReady) return;
+      await pool.query("CREATE EXTENSION IF NOT EXISTS timescaledb");
+      await pool.query(`
+        CREATE TABLE IF NOT EXISTS derivatives_market (
+          symbol text NOT NULL,
+          interval text NOT NULL,
+          ts timestamptz NOT NULL,
+          open_interest double precision,
+          funding_rate double precision,
+          liq_long double precision,
+          liq_short double precision,
+          liq_total double precision,
+          source text,
+          ingested_at timestamptz NOT NULL DEFAULT now(),
+          PRIMARY KEY (symbol, interval, ts)
+        )
+      `);
+      await pool.query(`
+        SELECT create_hypertable(
+          'derivatives_market',
+          'ts',
+          if_not_exists => TRUE,
+          chunk_time_interval => interval '14 days'
+        )
+      `);
+      await pool.query(`
+        CREATE INDEX IF NOT EXISTS derivatives_market_symbol_tf_ts_idx
+        ON derivatives_market (symbol, interval, ts DESC)
+      `);
+      await pool.query(`
+        CREATE TABLE IF NOT EXISTS derivatives_backfill_coverage (
+          source text NOT NULL,
+          symbol text NOT NULL,
+          interval text NOT NULL,
+          from_ts timestamptz NOT NULL,
+          to_ts timestamptz NOT NULL,
+          rows_count integer NOT NULL DEFAULT 0,
+          checked_at timestamptz NOT NULL DEFAULT now(),
+          PRIMARY KEY (source, symbol, interval, from_ts, to_ts)
+        )
+      `);
+      await pool.query(`
+        CREATE INDEX IF NOT EXISTS derivatives_backfill_coverage_lookup_idx
+        ON derivatives_backfill_coverage (source, symbol, interval, from_ts, to_ts)
+      `);
+      await pool.query(`
+        CREATE TABLE IF NOT EXISTS derivatives_metric_coverage (
+          source text NOT NULL,
+          metric text NOT NULL,
+          symbol text NOT NULL,
+          interval text NOT NULL,
+          from_ts timestamptz NOT NULL,
+          to_ts timestamptz NOT NULL,
+          event_rows_count integer NOT NULL DEFAULT 0,
+          zero_rows_count integer NOT NULL DEFAULT 0,
+          checked_at timestamptz NOT NULL DEFAULT now(),
+          PRIMARY KEY (source, metric, symbol, interval, from_ts, to_ts)
+        )
+      `);
+      await pool.query(`
+        CREATE INDEX IF NOT EXISTS derivatives_metric_coverage_lookup_idx
+        ON derivatives_metric_coverage (
+          source,
+          metric,
+          symbol,
+          interval,
+          from_ts,
+          to_ts
+        )
+      `);
+      derivativesSchemaReady = true;
+    }
+  ).finally(() => {
+    derivativesSchemaReadyPromise = null;
+  });
+  await derivativesSchemaReadyPromise;
+};
+var ensureBinanceMarketSchema = async () => {
+  if (binanceMarketSchemaReady) return;
+  if (binanceMarketSchemaReadyPromise) {
+    await binanceMarketSchemaReadyPromise;
+    return;
+  }
+  const pool = getPool();
+  binanceMarketSchemaReadyPromise = withSchemaLock(
+    BINANCE_MARKET_SCHEMA_LOCK_KEY,
+    async () => {
+      if (binanceMarketSchemaReady) return;
+      await pool.query("CREATE EXTENSION IF NOT EXISTS timescaledb");
+      await pool.query(`
+        CREATE TABLE IF NOT EXISTS market_trade_flow (
+          symbol text NOT NULL,
+          interval text NOT NULL,
+          ts timestamptz NOT NULL,
+          trades integer NOT NULL,
+          buy_base_volume double precision,
+          sell_base_volume double precision,
+          buy_quote_volume double precision,
+          sell_quote_volume double precision,
+          net_base_delta double precision,
+          net_quote_delta double precision,
+          buy_pressure_pct double precision,
+          source text,
+          ingested_at timestamptz NOT NULL DEFAULT now(),
+          PRIMARY KEY (symbol, interval, ts)
+        )
+      `);
+      await pool.query(`
+        SELECT create_hypertable(
+          'market_trade_flow',
+          'ts',
+          if_not_exists => TRUE,
+          chunk_time_interval => interval '7 days'
+        )
+      `);
+      await pool.query(`
+        CREATE INDEX IF NOT EXISTS market_trade_flow_symbol_tf_ts_idx
+        ON market_trade_flow (symbol, interval, ts DESC)
+      `);
+      await pool.query(`
+        CREATE TABLE IF NOT EXISTS market_breadth (
+          universe text NOT NULL,
+          interval text NOT NULL,
+          ts timestamptz NOT NULL,
+          symbols_count integer NOT NULL,
+          advancers integer NOT NULL,
+          decliners integer NOT NULL,
+          unchanged integer NOT NULL,
+          advance_decline_ratio double precision,
+          pct_above_ma20 double precision,
+          pct_above_ma50 double precision,
+          equal_weighted_return double precision,
+          volume_weighted_return double precision,
+          dispersion double precision,
+          btc_return_1h double precision,
+          btc_return_4h double precision,
+          btc_return_24h double precision,
+          alt_basket_return_1h double precision,
+          alt_basket_return_4h double precision,
+          alt_basket_return_24h double precision,
+          btc_vs_alt_return_1h double precision,
+          btc_vs_alt_return_4h double precision,
+          btc_vs_alt_return_24h double precision,
+          btc_turnover_share_1h double precision,
+          btc_turnover_share_24h double precision,
+          btc_turnover_share_change_24h double precision,
+          alt_vol_to_btc_vol_24h double precision,
+          alt_dispersion_24h double precision,
+          btc_alt_regime text,
+          source text,
+          ingested_at timestamptz NOT NULL DEFAULT now(),
+          PRIMARY KEY (universe, interval, ts)
+        )
+      `);
+      await pool.query(`
+        ALTER TABLE market_breadth
+          ADD COLUMN IF NOT EXISTS btc_return_1h double precision,
+          ADD COLUMN IF NOT EXISTS btc_return_4h double precision,
+          ADD COLUMN IF NOT EXISTS btc_return_24h double precision,
+          ADD COLUMN IF NOT EXISTS alt_basket_return_1h double precision,
+          ADD COLUMN IF NOT EXISTS alt_basket_return_4h double precision,
+          ADD COLUMN IF NOT EXISTS alt_basket_return_24h double precision,
+          ADD COLUMN IF NOT EXISTS btc_vs_alt_return_1h double precision,
+          ADD COLUMN IF NOT EXISTS btc_vs_alt_return_4h double precision,
+          ADD COLUMN IF NOT EXISTS btc_vs_alt_return_24h double precision,
+          ADD COLUMN IF NOT EXISTS btc_turnover_share_1h double precision,
+          ADD COLUMN IF NOT EXISTS btc_turnover_share_24h double precision,
+          ADD COLUMN IF NOT EXISTS btc_turnover_share_change_24h double precision,
+          ADD COLUMN IF NOT EXISTS alt_vol_to_btc_vol_24h double precision,
+          ADD COLUMN IF NOT EXISTS alt_dispersion_24h double precision,
+          ADD COLUMN IF NOT EXISTS btc_alt_regime text
+      `);
+      await pool.query(`
+        SELECT create_hypertable(
+          'market_breadth',
+          'ts',
+          if_not_exists => TRUE,
+          chunk_time_interval => interval '14 days'
+        )
+      `);
+      await pool.query(`
+        CREATE INDEX IF NOT EXISTS market_breadth_universe_tf_ts_idx
+        ON market_breadth (universe, interval, ts DESC)
+      `);
+      await pool.query(`
+        CREATE TABLE IF NOT EXISTS market_global_context (
+          source text NOT NULL,
+          ts timestamptz NOT NULL,
+          updated_at_ts timestamptz,
+          active_cryptocurrencies integer,
+          active_exchanges integer,
+          active_market_pairs integer,
+          markets integer,
+          total_market_cap_usd double precision,
+          total_volume_usd double precision,
+          total_volume_reported_usd double precision,
+          btc_dominance_pct double precision,
+          eth_dominance_pct double precision,
+          alt_market_cap_usd double precision,
+          alt_volume_usd double precision,
+          alt_volume_reported_usd double precision,
+          btc_to_alt_market_cap_ratio double precision,
+          market_cap_change_pct_24h_usd double precision,
+          ingested_at timestamptz NOT NULL DEFAULT now(),
+          PRIMARY KEY (source, ts)
+        )
+      `);
+      await pool.query(`
+        SELECT create_hypertable(
+          'market_global_context',
+          'ts',
+          if_not_exists => TRUE,
+          chunk_time_interval => interval '30 days'
+        )
+      `);
+      await pool.query(`
+        CREATE INDEX IF NOT EXISTS market_global_context_source_ts_idx
+        ON market_global_context (source, ts DESC)
+      `);
+      await pool.query(`
+        ALTER TABLE market_global_context
+          ADD COLUMN IF NOT EXISTS active_exchanges integer,
+          ADD COLUMN IF NOT EXISTS active_market_pairs integer,
+          ADD COLUMN IF NOT EXISTS total_volume_reported_usd double precision,
+          ADD COLUMN IF NOT EXISTS alt_volume_usd double precision,
+          ADD COLUMN IF NOT EXISTS alt_volume_reported_usd double precision
+      `);
+      await pool.query(`
+        CREATE TABLE IF NOT EXISTS market_reference_asset_context (
+          source text NOT NULL,
+          symbol text NOT NULL,
+          cmc_id integer NOT NULL,
+          interval text NOT NULL,
+          ts timestamptz NOT NULL,
+          open_usd double precision,
+          high_usd double precision,
+          low_usd double precision,
+          close_usd double precision,
+          volume_usd double precision,
+          market_cap_usd double precision,
+          ingested_at timestamptz NOT NULL DEFAULT now(),
+          PRIMARY KEY (source, symbol, interval, ts)
+        )
+      `);
+      await pool.query(`
+        SELECT create_hypertable(
+          'market_reference_asset_context',
+          'ts',
+          if_not_exists => TRUE,
+          chunk_time_interval => interval '30 days'
+        )
+      `);
+      await pool.query(`
+        CREATE INDEX IF NOT EXISTS market_reference_asset_context_lookup_idx
+        ON market_reference_asset_context (source, symbol, interval, ts DESC)
+      `);
+      await pool.query(`
+        CREATE TABLE IF NOT EXISTS market_cmc_exchange_liquidity_context (
+          source text NOT NULL,
+          interval text NOT NULL,
+          ts timestamptz NOT NULL,
+          exchanges_count integer NOT NULL,
+          total_volume_usd double precision,
+          binance_volume_usd double precision,
+          binance_volume_share double precision,
+          top_exchange_volume_share double precision,
+          liquidity_regime text,
+          ingested_at timestamptz NOT NULL DEFAULT now(),
+          PRIMARY KEY (source, interval, ts)
+        )
+      `);
+      await pool.query(`
+        SELECT create_hypertable(
+          'market_cmc_exchange_liquidity_context',
+          'ts',
+          if_not_exists => TRUE,
+          chunk_time_interval => interval '30 days'
+        )
+      `);
+      await pool.query(`
+        CREATE INDEX IF NOT EXISTS market_cmc_exchange_liquidity_context_lookup_idx
+        ON market_cmc_exchange_liquidity_context (source, interval, ts DESC)
+      `);
+      await pool.query(`
+        CREATE TABLE IF NOT EXISTS market_cmc_fear_greed_context (
+          source text NOT NULL,
+          interval text NOT NULL,
+          ts timestamptz NOT NULL,
+          value integer NOT NULL,
+          classification text NOT NULL,
+          sentiment_regime text NOT NULL,
+          ingested_at timestamptz NOT NULL DEFAULT now(),
+          PRIMARY KEY (source, interval, ts)
+        )
+      `);
+      await pool.query(`
+        SELECT create_hypertable(
+          'market_cmc_fear_greed_context',
+          'ts',
+          if_not_exists => TRUE,
+          chunk_time_interval => interval '30 days'
+        )
+      `);
+      await pool.query(`
+        CREATE INDEX IF NOT EXISTS market_cmc_fear_greed_context_lookup_idx
+        ON market_cmc_fear_greed_context (source, interval, ts DESC)
+      `);
+      await pool.query(`
+        CREATE TABLE IF NOT EXISTS market_cmc_index_context (
+          source text NOT NULL,
+          index_slug text NOT NULL,
+          interval text NOT NULL,
+          ts timestamptz NOT NULL,
+          value double precision NOT NULL,
+          constituents_count integer,
+          top_constituent_symbol text,
+          top_constituent_weight_pct double precision,
+          constituents jsonb,
+          ingested_at timestamptz NOT NULL DEFAULT now(),
+          PRIMARY KEY (source, index_slug, interval, ts)
+        )
+      `);
+      await pool.query(`
+        SELECT create_hypertable(
+          'market_cmc_index_context',
+          'ts',
+          if_not_exists => TRUE,
+          chunk_time_interval => interval '30 days'
+        )
+      `);
+      await pool.query(`
+        CREATE INDEX IF NOT EXISTS market_cmc_index_context_lookup_idx
+        ON market_cmc_index_context (source, index_slug, interval, ts DESC)
+      `);
+      await pool.query(`
+        CREATE TABLE IF NOT EXISTS market_context_backfill_coverage (
+          source text NOT NULL,
+          scope text NOT NULL,
+          interval text NOT NULL,
+          from_ts timestamptz NOT NULL,
+          to_ts timestamptz NOT NULL,
+          rows_count integer NOT NULL DEFAULT 0,
+          checked_at timestamptz NOT NULL DEFAULT now(),
+          PRIMARY KEY (source, scope, interval, from_ts, to_ts)
+        )
+      `);
+      await pool.query(`
+        CREATE INDEX IF NOT EXISTS market_context_backfill_coverage_lookup_idx
+        ON market_context_backfill_coverage (source, scope, interval, from_ts, to_ts)
+      `);
+      binanceMarketSchemaReady = true;
+    }
+  ).finally(() => {
+    binanceMarketSchemaReadyPromise = null;
+  });
+  await binanceMarketSchemaReadyPromise;
+};
+var ensureHyperliquidWhaleSchema = async () => {
+  if (hyperliquidWhaleSchemaReady) return;
+  if (hyperliquidWhaleSchemaReadyPromise) {
+    await hyperliquidWhaleSchemaReadyPromise;
+    return;
+  }
+  hyperliquidWhaleSchemaReadyPromise = withSchemaLock(
+    HYPERLIQUID_WHALE_SCHEMA_LOCK_KEY,
+    async () => {
+      if (hyperliquidWhaleSchemaReady) return;
+      const pool = getPool();
+      await pool.query("CREATE EXTENSION IF NOT EXISTS timescaledb");
+      await pool.query(`
+        CREATE TABLE IF NOT EXISTS hyperliquid_whale_trade_events (
+          symbol text NOT NULL,
+          ts timestamptz NOT NULL,
+          tid text NOT NULL,
+          price double precision NOT NULL,
+          size double precision NOT NULL,
+          notional_usd double precision NOT NULL,
+          buyer_address text,
+          seller_address text,
+          buyer_tracked boolean NOT NULL,
+          seller_tracked boolean NOT NULL,
+          buyer_start_position double precision,
+          buyer_end_position double precision,
+          buyer_position_action text,
+          buyer_closed_pnl double precision,
+          buyer_liquidation boolean,
+          seller_start_position double precision,
+          seller_end_position double precision,
+          seller_position_action text,
+          seller_closed_pnl double precision,
+          seller_liquidation boolean,
+          universe_fingerprint text NOT NULL,
+          whale_registry_fingerprint text NOT NULL,
+          source text,
+          ingested_at timestamptz NOT NULL DEFAULT now(),
+          PRIMARY KEY (
+            universe_fingerprint,
+            whale_registry_fingerprint,
+            symbol,
+            ts,
+            tid
+          )
+        )
+      `);
+      await pool.query(`
+        ALTER TABLE hyperliquid_whale_trade_events
+          ADD COLUMN IF NOT EXISTS buyer_start_position double precision,
+          ADD COLUMN IF NOT EXISTS buyer_end_position double precision,
+          ADD COLUMN IF NOT EXISTS buyer_position_action text,
+          ADD COLUMN IF NOT EXISTS buyer_closed_pnl double precision,
+          ADD COLUMN IF NOT EXISTS buyer_liquidation boolean,
+          ADD COLUMN IF NOT EXISTS seller_start_position double precision,
+          ADD COLUMN IF NOT EXISTS seller_end_position double precision,
+          ADD COLUMN IF NOT EXISTS seller_position_action text,
+          ADD COLUMN IF NOT EXISTS seller_closed_pnl double precision,
+          ADD COLUMN IF NOT EXISTS seller_liquidation boolean
+      `);
+      await pool.query(`
+        SELECT create_hypertable(
+          'hyperliquid_whale_trade_events',
+          'ts',
+          if_not_exists => TRUE,
+          chunk_time_interval => interval '1 day'
+        )
+      `);
+      await pool.query(`
+        CREATE INDEX IF NOT EXISTS hyperliquid_whale_events_lookup_idx
+        ON hyperliquid_whale_trade_events (
+          universe_fingerprint,
+          whale_registry_fingerprint,
+          symbol,
+          ts DESC
+        )
+      `);
+      await pool.query(`
+        CREATE TABLE IF NOT EXISTS hyperliquid_whale_flow (
+          symbol text NOT NULL,
+          interval text NOT NULL,
+          ts timestamptz NOT NULL,
+          trades integer NOT NULL,
+          whale_sides integer NOT NULL,
+          unique_whales integer NOT NULL,
+          whale_addresses text[] NOT NULL DEFAULT '{}',
+          buy_notional_usd double precision NOT NULL,
+          sell_notional_usd double precision NOT NULL,
+          net_notional_usd double precision NOT NULL,
+          buy_share_pct double precision,
+          position_aware_whale_sides integer NOT NULL DEFAULT 0,
+          long_entry_whale_addresses text[] NOT NULL DEFAULT '{}',
+          short_entry_whale_addresses text[] NOT NULL DEFAULT '{}',
+          long_exit_whale_addresses text[] NOT NULL DEFAULT '{}',
+          short_exit_whale_addresses text[] NOT NULL DEFAULT '{}',
+          long_entry_notional_usd double precision NOT NULL DEFAULT 0,
+          short_entry_notional_usd double precision NOT NULL DEFAULT 0,
+          long_exit_notional_usd double precision NOT NULL DEFAULT 0,
+          short_exit_notional_usd double precision NOT NULL DEFAULT 0,
+          entry_net_notional_usd double precision NOT NULL DEFAULT 0,
+          entry_long_share_pct double precision,
+          universe_fingerprint text NOT NULL,
+          whale_registry_fingerprint text NOT NULL,
+          source text,
+          ingested_at timestamptz NOT NULL DEFAULT now(),
+          PRIMARY KEY (
+            universe_fingerprint,
+            whale_registry_fingerprint,
+            symbol,
+            interval,
+            ts
+          )
+        )
+      `);
+      await pool.query(`
+        ALTER TABLE hyperliquid_whale_flow
+          ADD COLUMN IF NOT EXISTS position_aware_whale_sides integer NOT NULL DEFAULT 0,
+          ADD COLUMN IF NOT EXISTS long_entry_whale_addresses text[] NOT NULL DEFAULT '{}',
+          ADD COLUMN IF NOT EXISTS short_entry_whale_addresses text[] NOT NULL DEFAULT '{}',
+          ADD COLUMN IF NOT EXISTS long_exit_whale_addresses text[] NOT NULL DEFAULT '{}',
+          ADD COLUMN IF NOT EXISTS short_exit_whale_addresses text[] NOT NULL DEFAULT '{}',
+          ADD COLUMN IF NOT EXISTS long_entry_notional_usd double precision NOT NULL DEFAULT 0,
+          ADD COLUMN IF NOT EXISTS short_entry_notional_usd double precision NOT NULL DEFAULT 0,
+          ADD COLUMN IF NOT EXISTS long_exit_notional_usd double precision NOT NULL DEFAULT 0,
+          ADD COLUMN IF NOT EXISTS short_exit_notional_usd double precision NOT NULL DEFAULT 0,
+          ADD COLUMN IF NOT EXISTS entry_net_notional_usd double precision NOT NULL DEFAULT 0,
+          ADD COLUMN IF NOT EXISTS entry_long_share_pct double precision
+      `);
+      await pool.query(`
+        SELECT create_hypertable(
+          'hyperliquid_whale_flow',
+          'ts',
+          if_not_exists => TRUE,
+          chunk_time_interval => interval '7 days'
+        )
+      `);
+      await pool.query(`
+        CREATE INDEX IF NOT EXISTS hyperliquid_whale_flow_lookup_idx
+        ON hyperliquid_whale_flow (
+          universe_fingerprint,
+          whale_registry_fingerprint,
+          symbol,
+          interval,
+          ts DESC
+        )
+      `);
+      await pool.query(`
+        CREATE TABLE IF NOT EXISTS hyperliquid_whale_wallet_coverage (
+          universe_fingerprint text NOT NULL,
+          whale_registry_fingerprint text NOT NULL,
+          address text NOT NULL,
+          requested_from_ts timestamptz NOT NULL,
+          requested_to_ts timestamptz NOT NULL,
+          covered_from_ts timestamptz,
+          covered_to_ts timestamptz,
+          status text NOT NULL CHECK (status IN ('complete', 'truncated', 'failed')),
+          fills_count integer NOT NULL DEFAULT 0,
+          error text,
+          data_model_version integer NOT NULL DEFAULT 2,
+          checked_at timestamptz NOT NULL DEFAULT now(),
+          PRIMARY KEY (
+            universe_fingerprint,
+            whale_registry_fingerprint,
+            address,
+            requested_from_ts,
+            requested_to_ts
+          )
+        )
+      `);
+      await pool.query(`
+        ALTER TABLE hyperliquid_whale_wallet_coverage
+          ADD COLUMN IF NOT EXISTS data_model_version integer NOT NULL DEFAULT 2
+      `);
+      await pool.query(`
+        CREATE INDEX IF NOT EXISTS hyperliquid_whale_wallet_coverage_lookup_idx
+        ON hyperliquid_whale_wallet_coverage (
+          universe_fingerprint,
+          whale_registry_fingerprint,
+          address,
+          requested_from_ts,
+          requested_to_ts
+        )
+      `);
+      await pool.query(`
+        CREATE TABLE IF NOT EXISTS hyperliquid_whale_coverage_1m (
+          ts timestamptz NOT NULL,
+          covered_whales integer NOT NULL,
+          expected_whales integer NOT NULL,
+          coverage_pct double precision NOT NULL,
+          universe_fingerprint text NOT NULL,
+          whale_registry_fingerprint text NOT NULL,
+          source text,
+          data_model_version integer NOT NULL DEFAULT 2,
+          ingested_at timestamptz NOT NULL DEFAULT now(),
+          PRIMARY KEY (
+            universe_fingerprint,
+            whale_registry_fingerprint,
+            ts
+          )
+        )
+      `);
+      await pool.query(`
+        ALTER TABLE hyperliquid_whale_coverage_1m
+          ADD COLUMN IF NOT EXISTS data_model_version integer NOT NULL DEFAULT 2
+      `);
+      await pool.query(`
+        SELECT create_hypertable(
+          'hyperliquid_whale_coverage_1m',
+          'ts',
+          if_not_exists => TRUE,
+          chunk_time_interval => interval '7 days'
+        )
+      `);
+      await pool.query(`
+        CREATE INDEX IF NOT EXISTS hyperliquid_whale_coverage_1m_lookup_idx
+        ON hyperliquid_whale_coverage_1m (
+          universe_fingerprint,
+          whale_registry_fingerprint,
+          ts DESC
+        )
+      `);
+      hyperliquidWhaleSchemaReady = true;
+    }
+  ).finally(() => {
+    hyperliquidWhaleSchemaReadyPromise = null;
+  });
+  await hyperliquidWhaleSchemaReadyPromise;
+};
+var ensureCoinMarketCapContextSchema = async () => ensureBinanceMarketSchema();
+var ensureMarketContextSchema = async (source) => {
+  switch (source) {
+    case "binance":
+      return ensureBinanceMarketSchema();
+    case "coinmarketcap":
+      return ensureCoinMarketCapContextSchema();
+    case "derivatives":
+      return ensureDerivativesSchema();
+    case "hyperliquidWhales":
+      return ensureHyperliquidWhaleSchema();
+  }
+};
+var MARKET_CONTEXT_SCHEMA_TABLES = {
+  binance: ["market_trade_flow", "market_breadth"],
+  coinmarketcap: [
+    "market_global_context",
+    "market_reference_asset_context",
+    "market_cmc_exchange_liquidity_context",
+    "market_cmc_fear_greed_context",
+    "market_cmc_index_context"
+  ],
+  derivatives: ["derivatives_market"],
+  hyperliquidWhales: [
+    "hyperliquid_whale_flow",
+    "hyperliquid_whale_coverage_1m"
+  ]
+};
+var verifyMarketContextSchema = async (source) => {
+  if (verifiedMarketContextSchemas.has(source)) return;
+  const tables = MARKET_CONTEXT_SCHEMA_TABLES[source];
+  const result = await queryMarketContext(
+    `
+      SELECT table_name AS "tableName"
+      FROM unnest($1::text[]) AS requested(table_name)
+      WHERE to_regclass(requested.table_name) IS NULL
+    `,
+    [tables]
+  );
+  if (result.rows.length) {
+    throw new Error(
+      `Timescale ${source} schema is not prepared; missing: ${result.rows.map((row) => row.tableName).filter(Boolean).join(", ")}`
+    );
+  }
+  verifiedMarketContextSchemas.add(source);
+};
+var prepareMarketContextSchemaForRead = async (source) => marketContextSchemaMode === "verify" ? verifyMarketContextSchema(source) : ensureMarketContextSchema(source);
+
+// src/timescale/derivatives.ts
+async function upsertDerivatives(rows) {
+  if (!rows.length) return;
+  await ensureDerivativesSchema();
+  const pool = getPool();
+  const cols = [
+    "symbol",
+    "interval",
+    "ts",
+    "open_interest",
+    "funding_rate",
+    "liq_long",
+    "liq_short",
+    "liq_total",
+    "source"
+  ];
+  const maxRows = Math.floor(65535 / cols.length);
+  if (rows.length > maxRows) {
+    for (let i = 0; i < rows.length; i += maxRows) {
+      await upsertDerivatives(rows.slice(i, i + maxRows));
+    }
+    return;
+  }
+  const valuesSql = rows.map(
+    (_, i) => `(${cols.map((__, j) => `$${i * cols.length + j + 1}`).join(",")})`
+  ).join(",");
+  const flat = rows.flatMap((row) => [
+    row.symbol,
+    row.interval,
+    row.ts,
+    row.openInterest ?? null,
+    row.fundingRate ?? null,
+    row.liqLong ?? null,
+    row.liqShort ?? null,
+    row.liqTotal ?? null,
+    row.source ?? null
+  ]);
+  const sql = `
+    INSERT INTO derivatives_market (${cols.join(",")})
+    VALUES ${valuesSql}
+    ON CONFLICT (symbol, interval, ts) DO UPDATE SET
+      open_interest = COALESCE(EXCLUDED.open_interest, derivatives_market.open_interest),
+      funding_rate = COALESCE(EXCLUDED.funding_rate, derivatives_market.funding_rate),
+      liq_long = COALESCE(EXCLUDED.liq_long, derivatives_market.liq_long),
+      liq_short = COALESCE(EXCLUDED.liq_short, derivatives_market.liq_short),
+      liq_total = COALESCE(EXCLUDED.liq_total, derivatives_market.liq_total),
+      source = COALESCE(EXCLUDED.source, derivatives_market.source),
+      ingested_at = now()
+  `;
+  await pool.query(sql, flat);
+}
+async function getDerivativesRangeForSymbols(symbols, interval, startMs, endMs) {
+  if (!symbols.length)
+    return [];
+  await ensureDerivativesSchema();
+  const pool = getPool();
+  const sql = `
+    SELECT symbol, interval, ts, open_interest, funding_rate, liq_long, liq_short, liq_total
+    FROM derivatives_market
+    WHERE symbol = ANY($1)
+      AND interval = $2
+      AND ts >= to_timestamp($3/1000.0)
+      AND ts <= to_timestamp($4/1000.0)
+    ORDER BY symbol ASC, ts ASC
+  `;
+  const res = await pool.query(sql, [symbols, interval, startMs, endMs]);
+  return res.rows;
+}
+async function getDerivativesDataEdgesForSymbols(symbols, interval) {
+  const normalizedSymbols = [
+    ...new Set(
+      symbols.map(
+        (symbol) => String(symbol || "").trim().toUpperCase()
+      ).filter(Boolean)
+    )
+  ];
+  const edges = /* @__PURE__ */ new Map();
+  if (!normalizedSymbols.length) return edges;
+  await ensureDerivativesSchema();
+  const pool = getPool();
+  const sql = `
+    SELECT
+      symbol,
+      extract(epoch from MIN(ts))*1000 AS min,
+      extract(epoch from MAX(ts))*1000 AS max
+    FROM derivatives_market
+    WHERE symbol = ANY($1)
+      AND interval = $2
+    GROUP BY symbol
+  `;
+  const res = await pool.query(sql, [normalizedSymbols, interval]);
+  for (const row of res.rows) {
+    const min = Number(row.min);
+    const max = Number(row.max);
+    edges.set(String(row.symbol).toUpperCase(), {
+      min: Number.isFinite(min) ? min : void 0,
+      max: Number.isFinite(max) ? max : void 0
+    });
+  }
+  return edges;
+}
+async function getDerivativesBackfillCoverage(params) {
+  const normalizedSource = String(params.source || "").trim().toLowerCase();
+  const normalizedSymbols = [
+    ...new Set(
+      params.symbols.map(
+        (symbol) => String(symbol || "").trim().toUpperCase()
+      ).filter(Boolean)
+    )
+  ];
+  if (!normalizedSource || !normalizedSymbols.length) {
+    return [];
+  }
+  await ensureDerivativesSchema();
+  const pool = getPool();
+  const res = await pool.query(
+    `
+      SELECT
+        symbol,
+        interval,
+        extract(epoch from from_ts)*1000 AS from_ms,
+        extract(epoch from to_ts)*1000 AS to_ms,
+        rows_count
+      FROM derivatives_backfill_coverage
+      WHERE source = $1
+        AND symbol = ANY($2)
+        AND interval = $3
+        AND from_ts <= to_timestamp($5/1000.0)
+        AND to_ts >= to_timestamp($4/1000.0)
+    `,
+    [
+      normalizedSource,
+      normalizedSymbols,
+      params.interval,
+      params.fromMs,
+      params.toMs
+    ]
+  );
+  return res.rows.map((row) => ({
+    symbol: String(row.symbol).toUpperCase(),
+    interval: row.interval,
+    fromMs: Number(row.from_ms),
+    toMs: Number(row.to_ms),
+    rowsCount: Number(row.rows_count ?? 0)
+  }));
+}
+async function upsertDerivativesBackfillCoverage(rows) {
+  if (!rows.length) return;
+  await ensureDerivativesSchema();
+  const pool = getPool();
+  const cols = [
+    "source",
+    "symbol",
+    "interval",
+    "from_ts",
+    "to_ts",
+    "rows_count"
+  ];
+  const valuesSql = rows.map(
+    (_, i) => `(${cols.map((__, j) => `$${i * cols.length + j + 1}`).join(",")})`
+  ).join(",");
+  const flat = rows.flatMap((row) => [
+    String(row.source || "").trim().toLowerCase(),
+    String(row.symbol || "").trim().toUpperCase(),
+    row.interval,
+    new Date(row.fromMs),
+    new Date(row.toMs),
+    Math.max(0, Math.trunc(row.rowsCount))
+  ]);
+  await pool.query(
+    `
+      INSERT INTO derivatives_backfill_coverage (${cols.join(",")})
+      VALUES ${valuesSql}
+      ON CONFLICT (source, symbol, interval, from_ts, to_ts) DO UPDATE SET
+        rows_count = EXCLUDED.rows_count,
+        checked_at = now()
+    `,
+    flat
+  );
+}
+async function getDerivativesMetricCoverage(params) {
+  const normalizedSource = String(params.source || "").trim().toLowerCase();
+  const normalizedSymbols = [
+    ...new Set(
+      params.symbols.map(
+        (symbol) => String(symbol || "").trim().toUpperCase()
+      ).filter(Boolean)
+    )
+  ];
+  if (!normalizedSource || !normalizedSymbols.length) {
+    return [];
+  }
+  await ensureDerivativesSchema();
+  const pool = getPool();
+  const res = await pool.query(
+    `
+      SELECT
+        symbol,
+        interval,
+        extract(epoch from from_ts)*1000 AS from_ms,
+        extract(epoch from to_ts)*1000 AS to_ms,
+        event_rows_count,
+        zero_rows_count
+      FROM derivatives_metric_coverage
+      WHERE source = $1
+        AND metric = $2
+        AND symbol = ANY($3)
+        AND interval = $4
+        AND from_ts <= to_timestamp($6/1000.0)
+        AND to_ts >= to_timestamp($5/1000.0)
+    `,
+    [
+      normalizedSource,
+      params.metric,
+      normalizedSymbols,
+      params.interval,
+      params.fromMs,
+      params.toMs
+    ]
+  );
+  return res.rows.map((row) => ({
+    symbol: String(row.symbol).toUpperCase(),
+    interval: row.interval,
+    fromMs: Number(row.from_ms),
+    toMs: Number(row.to_ms),
+    eventRowsCount: Number(row.event_rows_count ?? 0),
+    zeroRowsCount: Number(row.zero_rows_count ?? 0)
+  }));
+}
+async function applyDerivativesMetricCoverage(rows) {
+  if (!rows.length)
+    return [];
+  await ensureDerivativesSchema();
+  const pool = getPool();
+  const client = await pool.connect();
+  const results = [];
+  try {
+    await client.query("BEGIN");
+    for (const row of rows) {
+      const source = String(row.source || "").trim().toLowerCase();
+      const symbol = String(row.symbol || "").trim().toUpperCase();
+      const fromMs = Math.trunc(row.fromMs);
+      const toMs = Math.trunc(row.toMs);
+      if (!source || !symbol || fromMs > toMs) continue;
+      await client.query(
+        `
+          UPDATE derivatives_market
+          SET
+            liq_long = 0,
+            liq_short = 0,
+            liq_total = 0,
+            ingested_at = now()
+          WHERE symbol = $1
+            AND interval = $2
+            AND ts >= to_timestamp($3/1000.0)
+            AND ts <= to_timestamp($4/1000.0)
+            AND liq_long IS NULL
+            AND liq_short IS NULL
+            AND liq_total IS NULL
+        `,
+        [symbol, row.interval, fromMs, toMs]
+      );
+      const zeroCountResult = await client.query(
+        `
+          SELECT COUNT(*)::integer AS count
+          FROM derivatives_market
+          WHERE symbol = $1
+            AND interval = $2
+            AND ts >= to_timestamp($3/1000.0)
+            AND ts <= to_timestamp($4/1000.0)
+            AND liq_long = 0
+            AND liq_short = 0
+            AND liq_total = 0
+        `,
+        [symbol, row.interval, fromMs, toMs]
+      );
+      const zeroRowsCount = Math.max(
+        0,
+        Number(zeroCountResult.rows[0]?.count ?? 0)
+      );
+      await client.query(
+        `
+          INSERT INTO derivatives_metric_coverage (
+            source,
+            metric,
+            symbol,
+            interval,
+            from_ts,
+            to_ts,
+            event_rows_count,
+            zero_rows_count
+          )
+          VALUES ($1, $2, $3, $4, $5, $6, $7, $8)
+          ON CONFLICT (source, metric, symbol, interval, from_ts, to_ts)
+          DO UPDATE SET
+            event_rows_count = EXCLUDED.event_rows_count,
+            zero_rows_count = EXCLUDED.zero_rows_count,
+            checked_at = now()
+        `,
+        [
+          source,
+          row.metric,
+          symbol,
+          row.interval,
+          new Date(fromMs),
+          new Date(toMs),
+          Math.max(0, Math.trunc(row.eventRowsCount)),
+          zeroRowsCount
+        ]
+      );
+      results.push({ symbol, zeroRowsCount });
+    }
+    await client.query("COMMIT");
+    return results;
+  } catch (error) {
+    await client.query("ROLLBACK");
+    throw error;
+  } finally {
+    client.release();
+  }
+}
+async function getDerivativesWindow(params) {
+  const { symbol, intervals, endMs, lookbackMs } = params;
+  const normalizedSymbol = String(symbol || "").trim().toUpperCase();
+  const normalizedIntervals = [...new Set(intervals)].filter(Boolean);
+  if (!normalizedSymbol || !normalizedIntervals.length) {
+    return {};
+  }
+  await prepareMarketContextSchemaForRead("derivatives");
+  const startMs = endMs - Math.max(0, lookbackMs);
+  const sql = `
+    SELECT symbol, interval, ts, open_interest, funding_rate, liq_long, liq_short, liq_total, source
+    FROM derivatives_market
+    WHERE symbol = $1
+      AND interval = ANY($2)
+      AND ts >= to_timestamp($3/1000.0)
+      AND ts <= to_timestamp($4/1000.0)
+    ORDER BY interval ASC, ts ASC
+  `;
+  const res = await queryMarketContext(
+    sql,
+    [normalizedSymbol, normalizedIntervals, startMs, endMs],
+    params
+  );
+  const rowsByInterval = {};
+  for (const row of res.rows) {
+    const interval = row.interval;
+    rowsByInterval[interval] ??= [];
+    rowsByInterval[interval]?.push({
+      symbol: row.symbol,
+      interval,
+      ts: row.ts,
+      openInterest: row.open_interest,
+      fundingRate: row.funding_rate,
+      liqLong: row.liq_long,
+      liqShort: row.liq_short,
+      liqTotal: row.liq_total,
+      source: row.source
+    });
+  }
+  return rowsByInterval;
+}
+async function getDerivativesSummary(hours = 24, limit = 500, symbols) {
+  await ensureDerivativesSchema();
+  const pool = getPool();
+  const cappedHours = Math.max(1, Math.min(24 * 90, hours));
+  const cappedLimit = Math.max(10, Math.min(1e3, limit));
+  const normalizedSymbols = Array.isArray(symbols) ? [...new Set(symbols.map(normalizeCandleSymbol).filter(Boolean))] : [];
+  const symbolsFilterSql = normalizedSymbols.length ? "AND symbol = ANY($3)" : "";
+  const summaryQ = await pool.query(
+    `
+      WITH filtered AS (
+        SELECT
+          symbol,
+          interval,
+          ts,
+          open_interest,
+          funding_rate,
+          liq_long,
+          liq_short,
+          liq_total
+        FROM derivatives_market
+        WHERE ts >= now() - ($1 || ' hours')::interval
+          ${symbolsFilterSql}
+      ),
+      latest AS (
+        SELECT DISTINCT ON (symbol, interval)
+          symbol,
+          interval,
+          ts AS last_ts,
+          open_interest AS latest_open_interest,
+          funding_rate AS latest_funding_rate
+        FROM filtered
+        ORDER BY symbol ASC, interval ASC, ts DESC
+      ),
+      first AS (
+        SELECT DISTINCT ON (symbol, interval)
+          symbol,
+          interval,
+          ts AS first_ts,
+          open_interest AS first_open_interest,
+          funding_rate AS first_funding_rate
+        FROM filtered
+        ORDER BY symbol ASC, interval ASC, ts ASC
+      ),
+      aggregated AS (
+        SELECT
+          symbol,
+          interval,
+          COUNT(*)::int AS points,
+          SUM(COALESCE(liq_long, 0)) AS sum_liq_long,
+          SUM(COALESCE(liq_short, 0)) AS sum_liq_short,
+          SUM(COALESCE(liq_total, 0)) AS sum_liq_total
+        FROM filtered
+        GROUP BY symbol, interval
+      )
+      SELECT
+        aggregated.symbol,
+        aggregated.interval,
+        aggregated.points,
+        latest.last_ts,
+        first.first_ts,
+        latest.latest_open_interest,
+        first.first_open_interest,
+        latest.latest_funding_rate,
+        first.first_funding_rate,
+        aggregated.sum_liq_long,
+        aggregated.sum_liq_short,
+        aggregated.sum_liq_total
+      FROM aggregated
+      JOIN latest
+        ON latest.symbol = aggregated.symbol
+       AND latest.interval = aggregated.interval
+      JOIN first
+        ON first.symbol = aggregated.symbol
+       AND first.interval = aggregated.interval
+      ORDER BY aggregated.sum_liq_total DESC, aggregated.symbol ASC
+      LIMIT $2
+    `,
+    normalizedSymbols.length ? [String(cappedHours), cappedLimit, normalizedSymbols] : [String(cappedHours), cappedLimit]
+  );
+  const items = summaryQ.rows.map((row) => {
+    const latestOpenInterest = row.latest_open_interest == null ? null : Number(row.latest_open_interest);
+    const firstOpenInterest = row.first_open_interest == null ? null : Number(row.first_open_interest);
+    const latestFundingRate = row.latest_funding_rate == null ? null : Number(row.latest_funding_rate);
+    const firstFundingRate = row.first_funding_rate == null ? null : Number(row.first_funding_rate);
+    const oiChange = latestOpenInterest != null && firstOpenInterest != null ? latestOpenInterest - firstOpenInterest : null;
+    const oiChangePct = oiChange != null && firstOpenInterest != null && Number.isFinite(firstOpenInterest) && Math.abs(firstOpenInterest) > 0 ? oiChange / Math.abs(firstOpenInterest) * 100 : null;
+    const fundingChange = latestFundingRate != null && firstFundingRate != null ? latestFundingRate - firstFundingRate : null;
+    return {
+      symbol: row.symbol,
+      interval: row.interval,
+      points: Number(row.points || 0),
+      last_ts: row.last_ts,
+      first_ts: row.first_ts,
+      latest_open_interest: latestOpenInterest,
+      first_open_interest: firstOpenInterest,
+      oi_change: oiChange,
+      oi_change_pct: oiChangePct,
+      latest_funding_rate: latestFundingRate,
+      first_funding_rate: firstFundingRate,
+      funding_change: fundingChange,
+      sum_liq_long: row.sum_liq_long == null ? null : Number(row.sum_liq_long),
+      sum_liq_short: row.sum_liq_short == null ? null : Number(row.sum_liq_short),
+      sum_liq_total: row.sum_liq_total == null ? null : Number(row.sum_liq_total)
+    };
+  });
+  return {
+    hours: cappedHours,
+    items
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  applyDerivativesMetricCoverage,
+  ensureDerivativesSchema,
+  getDerivativesBackfillCoverage,
+  getDerivativesDataEdgesForSymbols,
+  getDerivativesMetricCoverage,
+  getDerivativesRangeForSymbols,
+  getDerivativesSummary,
+  getDerivativesWindow,
+  upsertDerivatives,
+  upsertDerivativesBackfillCoverage
+});