@livefolio/sdk 0.3.2 → 0.3.4

package/dist/index.js

@@ -96,6 +96,15 @@ function computeSma(bars, lookback) {
   }
   return result;
 }
+function smaInitialState(bars, lookback) {
+  if (bars.length < lookback) return null;
+  return { tail: bars.slice(-lookback).map((b) => b.value) };
+}
+function smaNext(prev, newRaw, lookback) {
+  const tail = [...prev.tail.slice(1), newRaw];
+  const sum = tail.reduce((a, b) => a + b, 0);
+  return { value: sum / lookback, state: { tail } };
+}
 
 // src/computations/ema.ts
 function computeEma(bars, lookback) {
@@ -112,6 +121,17 @@ function computeEma(bars, lookback) {
   }
   return result;
 }
+function emaInitialState(bars, lookback) {
+  if (bars.length < lookback) return null;
+  const series = computeEma(bars, lookback);
+  if (series.length === 0) return null;
+  return { ema: series[series.length - 1].value };
+}
+function emaNext(prev, newRaw, lookback) {
+  const multiplier = 2 / (lookback + 1);
+  const ema = newRaw * multiplier + prev.ema * (1 - multiplier);
+  return { value: ema, state: { ema } };
+}
 
 // src/computations/rsi.ts
 function computeRsi(bars, lookback) {
@@ -147,6 +167,34 @@ function computeRsi(bars, lookback) {
   }
   return result;
 }
+function rsiInitialState(bars, lookback) {
+  if (bars.length < lookback + 1) return null;
+  let avgGain = 0;
+  let avgLoss = 0;
+  for (let i = 1; i <= lookback; i++) {
+    const change = bars[i].value - bars[i - 1].value;
+    if (change > 0) avgGain += change;
+    else avgLoss += -change;
+  }
+  avgGain /= lookback;
+  avgLoss /= lookback;
+  let state = { avgGain, avgLoss, prev: bars[lookback].value };
+  for (let i = lookback + 1; i < bars.length; i++) {
+    const { state: next } = rsiNext(state, bars[i].value, lookback);
+    state = next;
+  }
+  return state;
+}
+function rsiNext(prev, newRaw, lookback) {
+  const change = newRaw - prev.prev;
+  const gain = change > 0 ? change : 0;
+  const loss = change < 0 ? -change : 0;
+  const avgGain = (prev.avgGain * (lookback - 1) + gain) / lookback;
+  const avgLoss = (prev.avgLoss * (lookback - 1) + loss) / lookback;
+  const rs = avgLoss === 0 ? 100 : avgGain / avgLoss;
+  const value = avgLoss === 0 ? 100 : 100 - 100 / (1 + rs);
+  return { value, state: { avgGain, avgLoss, prev: newRaw } };
+}
 
 // src/computations/returns.ts
 function computeReturns(bars, lookback, mode = "pct") {
@@ -160,6 +208,16 @@ function computeReturns(bars, lookback, mode = "pct") {
   }
   return result;
 }
+function returnInitialState(bars, lookback) {
+  if (bars.length < lookback + 1) return null;
+  return { tail: bars.slice(-(lookback + 1)).map((b) => b.value) };
+}
+function returnNext(prev, newRaw, lookback, mode = "pct") {
+  const tail = [...prev.tail.slice(1), newRaw];
+  const old = tail[0];
+  const value = mode === "abs" ? newRaw - old : (newRaw - old) / old;
+  return { value, state: { tail } };
+}
 
 // src/computations/volatility.ts
 function computeVolatility(bars, lookback) {
@@ -181,6 +239,18 @@ function computeVolatility(bars, lookback) {
   }
   return result;
 }
+function volatilityInitialState(bars, lookback) {
+  if (bars.length < lookback + 1) return null;
+  return { tail: bars.slice(-(lookback + 1)).map((b) => b.value) };
+}
+function volatilityNext(prev, newRaw, lookback) {
+  const tail = [...prev.tail.slice(1), newRaw];
+  const returns = [];
+  for (let i = 1; i < tail.length; i++) returns.push(tail[i] / tail[i - 1] - 1);
+  const mean = returns.reduce((s, r) => s + r, 0) / lookback;
+  const variance = returns.reduce((s, r) => s + (r - mean) ** 2, 0) / lookback;
+  return { value: Math.sqrt(variance), state: { tail } };
+}
 
 // src/computations/drawdown.ts
 function computeDrawdown(bars, lookback) {
@@ -195,6 +265,16 @@ function computeDrawdown(bars, lookback) {
   }
   return result;
 }
+function drawdownInitialState(bars, lookback) {
+  if (bars.length < lookback) return null;
+  return { tail: bars.slice(-lookback).map((b) => b.value) };
+}
+function drawdownNext(prev, newRaw, _lookback) {
+  const tail = [...prev.tail.slice(1), newRaw];
+  let max = -Infinity;
+  for (const v of tail) if (v > max) max = v;
+  return { value: (newRaw - max) / max, state: { tail } };
+}
 
 // src/computations/calendar.ts
 function dayOfYear(d) {
@@ -237,36 +317,42 @@ var COMPUTATIONS = {
 function getComputation(type) {
   return COMPUTATIONS[type] ?? null;
 }
-
-// src/providers/quote-overlay.ts
-function createQuoteOverlay(base, overridesByDate, options = {}) {
-  return {
-    async fetchBars(symbol, from) {
-      const bars = await base.fetchBars(symbol, from);
-      const dates = Object.keys(overridesByDate).sort();
-      if (dates.length === 0) return bars;
-      const result = [...bars];
-      for (const date of dates) {
-        const overrideValue = overridesByDate[date][symbol];
-        let value = overrideValue;
-        if (value === void 0) {
-          if (!options.fallbackMissingQuotes) continue;
-          if (result.length === 0) continue;
-          value = result[result.length - 1].value;
-        }
-        const existingIdx = result.findIndex((b) => b.date === date);
-        if (existingIdx >= 0) {
-          result[existingIdx] = { date, value };
-        } else {
-          result.push({ date, value });
-        }
-      }
-      return result;
-    }
-  };
+var NEXT = {
+  SMA: smaNext,
+  EMA: emaNext,
+  RSI: rsiNext,
+  Return: ((prev, newRaw, lookback) => returnNext(prev, newRaw, lookback, "pct")),
+  Volatility: volatilityNext,
+  Drawdown: drawdownNext
+};
+var SEED = {
+  SMA: smaInitialState,
+  EMA: emaInitialState,
+  RSI: rsiInitialState,
+  Return: returnInitialState,
+  Volatility: volatilityInitialState,
+  Drawdown: drawdownInitialState
+};
+function getNextComputation(type) {
+  return NEXT[type];
+}
+function getInitialStateFn(type) {
+  return SEED[type];
 }
 
 // src/handles/indicator.ts
+var FRED_SYMBOL_TO_TYPE = {
+  DGS3MO: "T3M",
+  DGS6MO: "T6M",
+  DGS1: "T1Y",
+  DGS2: "T2Y",
+  DGS3: "T3Y",
+  DGS5: "T5Y",
+  DGS7: "T7Y",
+  DGS10: "T10Y",
+  DGS20: "T20Y",
+  DGS30: "T30Y"
+};
 function _subtractCalendarDays(date, days) {
   const d = new Date(date);
   d.setUTCDate(d.getUTCDate() - days);
@@ -337,14 +423,24 @@ var IndicatorHandle = class _IndicatorHandle {
     const { id } = await this.resolve();
     const latestClosed = await this._getLatestClosedTradingDay();
     if (this._cachedAsOf === latestClosed) return;
+    let horizon = latestClosed;
+    if (this.delay > 0) {
+      const tradingDays = await this._storage.tradingDays.getRange();
+      const idx = tradingDays.indexOf(latestClosed);
+      if (idx >= this.delay) {
+        horizon = tradingDays[idx - this.delay];
+      }
+    }
     const latestSeries = await this._getLatestSeriesDate(id);
-    if (latestSeries === latestClosed) {
+    if (latestSeries === horizon) {
       this._cachedSeries = null;
       this._cachedAsOf = latestClosed;
       return;
     }
     if (!this._syncing) {
-      this._syncing = this._sync(latestSeries ?? void 0, latestClosed).finally(() => {
+      this._syncing = this._sync(latestSeries ?? void 0, latestClosed).catch((err) => {
+        console.warn("[sdk] indicator sync failed, using stored data:", err);
+      }).finally(() => {
         this._syncing = null;
       });
     }
@@ -355,6 +451,34 @@ var IndicatorHandle = class _IndicatorHandle {
   async _sync(fromDate, latestClosed) {
     const tickerSymbol = this.ticker?.symbol ?? null;
     const info = getProviderInfo(this.type, tickerSymbol);
+    if (info.provider === "none") return;
+    let horizon = latestClosed;
+    if (this.delay > 0) {
+      const tradingDays = await this._storage.tradingDays.getRange();
+      const idx = tradingDays.indexOf(latestClosed);
+      if (idx < this.delay) return;
+      horizon = tradingDays[idx - this.delay];
+    }
+    const nextFn = getNextComputation(this.type);
+    const seedFn = getInitialStateFn(this.type);
+    const { id } = await this.resolve();
+    const checkpoint = nextFn ? await this._storage.indicators.getLatestBar(id) : null;
+    if (fromDate && nextFn && seedFn && checkpoint && checkpoint.metadata != null && checkpoint.date < horizon) {
+      const rawBars = await this._fetchRawBarsForIncremental(info, checkpoint.date, horizon);
+      if (rawBars.length === 0) return;
+      const newBars = [];
+      let state = checkpoint.metadata;
+      for (const raw of rawBars) {
+        if (raw.date <= checkpoint.date) continue;
+        if (raw.date > horizon) break;
+        const step = this.type === "Return" && info.provider === "computed" && info.rateSeries ? returnNext(state, raw.value, this.lookback, "abs") : nextFn(state, raw.value, this.lookback);
+        newBars.push({ date: raw.date, value: step.value });
+        state = step.state;
+      }
+      if (newBars.length === 0) return;
+      await this._storage.indicators.writeSeries(id, newBars, { metadata: state });
+      return;
+    }
     let bars;
     switch (info.provider) {
       case "yahoo":
@@ -381,50 +505,78 @@ var IndicatorHandle = class _IndicatorHandle {
           if (!computeFn) throw new Error(`No computation found for type "${this.type}"`);
           bars = computeFn(priceBars, this.lookback);
         }
-        if (fromDate) {
-          bars = bars.filter((b) => b.date > fromDate);
-        }
+        if (fromDate) bars = bars.filter((b) => b.date > fromDate);
         break;
       }
       case "calendar": {
         const allDays = await this._storage.tradingDays.getRange();
         const dayBars = allDays.map((date) => ({ date, value: 0 }));
         bars = computeCalendar(dayBars, this.type);
-        if (fromDate) {
-          bars = bars.filter((b) => b.date > fromDate);
-        }
+        if (fromDate) bars = bars.filter((b) => b.date > fromDate);
         break;
       }
-      case "none":
-        return;
     }
     if (info.provider !== "computed") {
       bars = await this._applyLeverage(bars, fromDate);
     }
-    bars = bars.filter((b) => b.date <= latestClosed);
-    if (bars.length > 0) {
-      await this._upsertSeries(bars);
+    bars = bars.filter((b) => b.date <= horizon);
+    if (bars.length === 0) return;
+    let metadata = void 0;
+    if (seedFn) {
+      if (info.provider === "computed") {
+        const priceHandle = new _IndicatorHandle(this._storage, this._market, {
+          type: "Price",
+          ticker: this.ticker,
+          lookback: 0,
+          delay: 0,
+          unit: null,
+          threshold: null
+        });
+        const priceBars = (await priceHandle._querySeriesFromDb()).filter((b) => b.date <= horizon);
+        metadata = seedFn(priceBars, this.lookback) ?? void 0;
+      } else {
+        metadata = seedFn(bars, this.lookback) ?? void 0;
+      }
     }
+    await this._upsertSeries(bars, metadata);
   }
-  async _upsertSeries(bars) {
+  async _fetchRawBarsForIncremental(info, sinceDate, horizon) {
+    if (info.provider === "computed") {
+      const priceHandle = new _IndicatorHandle(this._storage, this._market, {
+        type: "Price",
+        ticker: this.ticker,
+        lookback: 0,
+        delay: 0,
+        unit: null,
+        threshold: null
+      });
+      await priceHandle._ensureFresh();
+      return (await priceHandle._querySeriesFromDb({ from: sinceDate })).filter(
+        (b) => b.date > sinceDate && b.date <= horizon
+      );
+    }
+    if (info.provider === "yahoo" || info.provider === "fred") {
+      const symbol = info.provider === "yahoo" ? info.symbol : info.seriesId;
+      const bars = await this._market.fetchBars(symbol, sinceDate);
+      return bars.filter((b) => b.date > sinceDate && b.date <= horizon);
+    }
+    if (info.provider === "calendar") {
+      const allDays = await this._storage.tradingDays.getRange();
+      const dayBars = allDays.map((date) => ({ date, value: 0 }));
+      return computeCalendar(dayBars, this.type).filter(
+        (b) => b.date > sinceDate && b.date <= horizon
+      );
+    }
+    return [];
+  }
+  async _upsertSeries(bars, metadata) {
     const { id } = await this.resolve();
-    await this._storage.indicators.writeSeries(id, bars);
+    await this._storage.indicators.writeSeries(id, bars, metadata !== void 0 ? { metadata } : void 0);
   }
   async _querySeriesFromDb(range) {
     const { id } = await this.resolve();
     return this._storage.indicators.getSeries(id, range);
   }
-  withMarket(market) {
-    if (market === this._market) return this;
-    return _IndicatorHandle.fromResolved(this._storage, market, this.id, {
-      type: this.type,
-      ticker: this.ticker,
-      lookback: this.lookback,
-      delay: this.delay,
-      unit: this.unit,
-      threshold: this.threshold
-    });
-  }
   /**
    * Apply leverage compounding to a raw bar series, anchored to a stored
    * leveraged value. Used by both `_sync` and `computeAt` so they stay
@@ -458,21 +610,21 @@ var IndicatorHandle = class _IndicatorHandle {
     return leveraged;
   }
   /**
-   * Compute the indicator's value at `date` using the given market (typically
-   * an overlay market for pre-close preview). Pure — no writes to storage.
+   * Compute the indicator's value at `date` without persisting anything, with
+   * optional live-quote `overrides` keyed by raw market symbol (the same symbol
+   * space `MarketProvider.fetchBars` uses — ticker symbols for Price/SMA/etc.,
+   * `^VIX` / `^VIX3M` for macro, FRED series IDs like `DGS3MO` for Treasury).
    *
-   * For fetched types (yahoo/fred): fetches a small window of bars from
-   * `market`, applies leverage compounding anchored to the stored leveraged
-   * value at the bar before `date`.
-   * For computed types (SMA, RSI, etc.): fetches enough raw price bars to
-   * cover the indicator's lookback from `market`, applies leverage anchored
-   * to the stored value just before the fetch window, runs the computation,
-   * and returns the value at `date`.
-   * For Threshold: returns the threshold constant.
-   * For calendar: computes calendar value from the trading days list.
-   * Returns null if the value cannot be computed.
+   * Bars for the underlying symbol are resolved storage-first when the market
+   * hasn't yet produced bars for `date` (trading day still open), and storage
+   * is the fallback whenever the remote fetch fails — see `_resolveRawBars`.
+   *
+   * For Threshold: returns the threshold constant. For calendar types: computed
+   * from `tradingDays.getRange()`. For all others: `_resolveRawBars` → leverage
+   * compounding (if any) → lookback-specific computation. Returns null if the
+   * value cannot be computed.
    */
-  async computeAt(market, date) {
+  async computeAt(date, overrides) {
     if (this.type === "Threshold") return this.threshold;
     const tickerSymbol = this.ticker?.symbol ?? null;
     const info = getProviderInfo(this.type, tickerSymbol);
@@ -484,8 +636,32 @@ var IndicatorHandle = class _IndicatorHandle {
       return computed.find((b) => b.date === date)?.value ?? null;
     }
     if (info.provider === "computed") {
-      const from2 = _subtractCalendarDays(date, this.lookback + 10);
-      const rawBars2 = await market.fetchBars(info.symbol, from2);
+      const nextFn = getNextComputation(this.type);
+      if (nextFn) {
+        const { id } = await this.resolve();
+        const checkpoint = await this._storage.indicators.getLatestBar(id);
+        if (checkpoint && checkpoint.metadata != null) {
+          const tradingDays = await this._storage.tradingDays.getRange();
+          const ckIdx = tradingDays.indexOf(checkpoint.date);
+          const tgtIdx = tradingDays.indexOf(date);
+          if (ckIdx >= 0 && tgtIdx === ckIdx + 1) {
+            const rawBar = await this._resolveRawBarAt(info.symbol, date, overrides);
+            if (rawBar === null) return null;
+            const step = this.type === "Return" && info.rateSeries ? returnNext(checkpoint.metadata, rawBar, this.lookback, "abs") : nextFn(checkpoint.metadata, rawBar, this.lookback);
+            return step.value;
+          }
+        }
+      }
+      let calendarDays;
+      if (this.type === "RSI") {
+        calendarDays = Math.max(this.lookback * 10, 90);
+      } else if (this.type === "EMA") {
+        calendarDays = Math.max(this.lookback * 5, 60);
+      } else {
+        calendarDays = Math.ceil(this.lookback * 1.5) + 15;
+      }
+      const from2 = _subtractCalendarDays(date, this.lookback + calendarDays);
+      const rawBars2 = await this._resolveRawBars(info.symbol, from2, date, overrides);
       const anchorDate = rawBars2.length > 0 ? rawBars2[0].date : void 0;
       const priceBars = await this._applyLeverage(rawBars2, anchorDate);
       const computeFn = getComputation(this.type);
@@ -494,8 +670,8 @@ var IndicatorHandle = class _IndicatorHandle {
       return computed.find((b) => b.date === date)?.value ?? null;
     }
     const symbol = info.provider === "yahoo" ? info.symbol : info.seriesId;
-    const from = _subtractCalendarDays(date, 5);
-    const rawBars = await market.fetchBars(symbol, from);
+    const from = _subtractCalendarDays(date, 15);
+    const rawBars = await this._resolveRawBars(symbol, from, date, overrides);
     const leverage = this.ticker?.leverage ?? 1;
     if (leverage === 1) {
       return rawBars.find((b) => b.date === date)?.value ?? null;
@@ -511,6 +687,93 @@ var IndicatorHandle = class _IndicatorHandle {
     const rawReturn = (rawBars[dateIdx].value - prevBar.value) / prevBar.value;
     return leveragedPrev * (1 + leverage * rawReturn);
   }
+  /**
+   * Raw (unleveraged) bars for `symbol` up through `date`, with the live quote
+   * from `overrides[symbol]` (if any) spliced in at `date`.
+   *
+   * Decision policy:
+   *   - `date` > `tradingDays.getLatestClosed()`: market has nothing for that
+   *     day yet — skip the remote fetch entirely and read from storage.
+   *   - otherwise: try `this._market.fetchBars(symbol, from)`. On failure, fall
+   *     back to storage — upstream HTTP providers (Yahoo / FRED) are flaky.
+   *
+   * After the base is resolved, `overrides[symbol]` is spliced at `date`
+   * (replaces the existing bar, or is appended in-order). When no override is
+   * present but `date` isn't in the base bars, the last known value is carried
+   * forward to `date` — this preserves the fallbackMissingQuotes behaviour the
+   * old overlay exposed so leverage compounding / computations always have a
+   * point at `date` to land on.
+   */
+  async _resolveRawBars(symbol, from, date, overrides) {
+    const latestClosed = await this._storage.tradingDays.getLatestClosed();
+    const closedForDate = latestClosed !== null && date <= latestClosed;
+    let bars;
+    if (closedForDate) {
+      try {
+        bars = await this._market.fetchBars(symbol, from);
+      } catch {
+        bars = await this._readStoredBars(symbol, from);
+      }
+    } else {
+      bars = await this._readStoredBars(symbol, from);
+    }
+    const override = overrides?.[symbol];
+    const existingIdx = bars.findIndex((b) => b.date === date);
+    if (override !== void 0) {
+      if (existingIdx >= 0) {
+        bars[existingIdx] = { date, value: override };
+      } else {
+        bars = [...bars, { date, value: override }].sort((a, b) => a.date.localeCompare(b.date));
+      }
+    } else if (existingIdx < 0 && bars.length > 0) {
+      bars = [...bars, { date, value: bars[bars.length - 1].value }];
+    }
+    return bars;
+  }
+  /**
+   * Resolve the single raw (unleveraged) value for `symbol` at `date`.
+   * Returns the override directly when present; otherwise delegates to
+   * `_resolveRawBars` with a one-day window and picks the matching bar.
+   */
+  async _resolveRawBarAt(symbol, date, overrides) {
+    const override = overrides?.[symbol];
+    if (override !== void 0) return override;
+    const bars = await this._resolveRawBars(symbol, date, date, overrides);
+    const hit = bars.find((b) => b.date === date);
+    return hit?.value ?? null;
+  }
+  /**
+   * Resolve raw (unleveraged) bars for a market symbol from storage. Maps:
+   *   - `^VIX`   → the VIX indicator's stored series
+   *   - `^VIX3M` → the VIX3M indicator's stored series
+   *   - `DGS*`   → the matching Treasury-tenor indicator's stored series
+   *   - anything else → the `Price` indicator for that ticker symbol with
+   *     `leverage = 1` (the raw contract that `MarketProvider.fetchBars` has).
+   *
+   * Returns `[]` when the resolved indicator has no stored bars yet.
+   */
+  async _readStoredBars(symbol, from) {
+    let identity;
+    if (symbol === "^VIX") {
+      identity = { type: "VIX", tickerId: null, lookback: 0, delay: 0, unit: null, threshold: null };
+    } else if (symbol === "^VIX3M") {
+      identity = { type: "VIX3M", tickerId: null, lookback: 0, delay: 0, unit: null, threshold: null };
+    } else if (FRED_SYMBOL_TO_TYPE[symbol]) {
+      identity = {
+        type: FRED_SYMBOL_TO_TYPE[symbol],
+        tickerId: null,
+        lookback: 0,
+        delay: 0,
+        unit: null,
+        threshold: null
+      };
+    } else {
+      const { id: tickerId } = await this._storage.tickers.findOrCreate(symbol, 1);
+      identity = { type: "Price", tickerId, lookback: 0, delay: 0, unit: null, threshold: null };
+    }
+    const { id } = await this._storage.indicators.findOrCreate(identity);
+    return this._storage.indicators.getSeries(id, { from });
+  }
   // ── Public data access ─────────────────────────────────────────────
   async series(range) {
     if (this.type === "Threshold") {
@@ -533,36 +796,37 @@ var IndicatorHandle = class _IndicatorHandle {
     return this._storage.indicators.getValue(id, date);
   }
   /**
-   * Read-only preview of the indicator series that includes an in-memory bar
-   * at `date` computed via `computeAt` against a quote-overlay market. Does
+   * Read-only preview of the indicator series with an in-memory bar at `date`
+   * computed via `computeAt` with the supplied live-quote `overrides`. Does
    * NOT write to `indicators_series`. Safe to call before market close.
    *
-   * @param date - Target trading day whose value is computed in-memory from
-   *   the overridden quotes. Must be in `tradingDays.getRange()`.
-   * @param quoteOverrides - Raw (unleveraged) quotes keyed by ticker symbol.
-   *   Symbols omitted here fall back to yesterday's close via the overlay.
+   * @param date - Target trading day whose value is computed in-memory.
+   *   Must be in `tradingDays.getRange()`.
+   * @param overrides - Raw (unleveraged) quotes keyed by market symbol.
+   *   Symbols omitted fall back to the last known value (see `_resolveRawBars`).
    * @param range - Optional filter applied to the returned bars.
    * @returns Stored historical bars plus (or with) today's in-memory value.
    */
-  async previewSeries(date, quoteOverrides, range) {
+  async previewSeries(date, overrides, range) {
     const tradingDays = await this._storage.tradingDays.getRange();
     if (!tradingDays.includes(date)) {
       throw new Error(`previewSeries: ${date} is not a trading day`);
     }
-    const overlay = createQuoteOverlay(this._market, { [date]: quoteOverrides }, { fallbackMissingQuotes: true });
     let bars;
     if (this.type === "Threshold") {
       bars = await this._syntheticThresholdSeries();
     } else {
       bars = await this._querySeriesFromDb();
     }
-    const todayValue = await this.computeAt(overlay, date);
-    if (todayValue !== null) {
-      const idx = bars.findIndex((b) => b.date === date);
-      if (idx >= 0) {
-        bars[idx] = { date, value: todayValue };
-      } else {
-        bars = [...bars, { date, value: todayValue }].sort((a, b) => a.date.localeCompare(b.date));
+    if (this.delay === 0) {
+      const todayValue = await this.computeAt(date, overrides);
+      if (todayValue !== null) {
+        const idx = bars.findIndex((b) => b.date === date);
+        if (idx >= 0) {
+          bars[idx] = { date, value: todayValue };
+        } else {
+          bars = [...bars, { date, value: todayValue }].sort((a, b) => a.date.localeCompare(b.date));
+        }
       }
     }
     if (range) {
@@ -652,15 +916,17 @@ var SignalHandle = class _SignalHandle {
   comparison;
   tolerance;
   _storage;
-  _market;
   _resolvedId = null;
   _resolving = null;
   _cachedSeries = null;
   _cachedAsOf = null;
   _syncing = null;
-  constructor(storage, market, identity) {
+  // The `market` parameter is kept in the signature for API compatibility with
+  // `new SignalHandle(storage, market, identity)` — signals no longer carry
+  // their own market reference since `computeAt` delegates to the indicator
+  // handles, which already hold one.
+  constructor(storage, _market, identity) {
     this._storage = storage;
-    this._market = market;
     this.indicator1 = identity.indicator1;
     this.indicator2 = identity.indicator2;
     this.comparison = identity.comparison;
@@ -708,15 +974,20 @@ var SignalHandle = class _SignalHandle {
     const { id } = await this.resolve();
     const latestClosed = await this._getLatestClosedTradingDay();
     if (this._cachedAsOf === latestClosed) return;
-    await Promise.all([this.indicator1.series(), this.indicator2.series()]);
     const latestSeries = await this._getLatestSignalSeriesDate(id);
     if (latestSeries === latestClosed) {
       this._cachedSeries = null;
       this._cachedAsOf = latestClosed;
       return;
     }
+    const isFastPath = await this._isSingleBarFastPath(latestSeries ?? void 0, latestClosed);
+    if (!isFastPath) {
+      await Promise.all([this.indicator1.series(), this.indicator2.series()]);
+    }
     if (!this._syncing) {
-      this._syncing = this._sync(latestSeries ?? void 0, latestClosed).finally(() => {
+      this._syncing = this._sync(latestSeries ?? void 0, latestClosed).catch((err) => {
+        console.warn("[sdk] signal sync failed, using stored data:", err);
+      }).finally(() => {
         this._syncing = null;
       });
     }
@@ -724,17 +995,61 @@ var SignalHandle = class _SignalHandle {
     this._cachedSeries = null;
     this._cachedAsOf = latestClosed;
   }
+  async _isSingleBarFastPath(fromDate, latestClosed) {
+    if (!fromDate) return false;
+    const tradingDays = await this._storage.tradingDays.getRange();
+    const fromIdx = tradingDays.indexOf(fromDate);
+    const closedIdx = tradingDays.indexOf(latestClosed);
+    return fromIdx >= 0 && closedIdx === fromIdx + 1;
+  }
   async _sync(fromDate, latestClosed) {
     const { id } = await this.resolve();
+    const absolute = ABSOLUTE_TOLERANCE_TYPES.has(this.indicator1.type);
+    if (fromDate) {
+      const tradingDays = await this._storage.tradingDays.getRange();
+      const fromIdx = tradingDays.indexOf(fromDate);
+      const closedIdx = tradingDays.indexOf(latestClosed);
+      if (fromIdx >= 0 && closedIdx === fromIdx + 1) {
+        const newDate = tradingDays[closedIdx];
+        const [v1, v2] = await Promise.all([
+          this.indicator1.computeAt(newDate, void 0),
+          this.indicator2.computeAt(newDate, void 0)
+        ]);
+        if (v1 === null || v2 === null) return;
+        const prev = await this._getLastSignalValue(id) ?? void 0;
+        const value = this._evaluateOneBar(v1, v2, absolute, prev);
+        await this._upsertSeries([{ date: newDate, value }]);
+        return;
+      }
+    }
     const range = fromDate ? { from: fromDate } : void 0;
     const [series1, series2] = await Promise.all([this.indicator1.series(range), this.indicator2.series(range)]);
     const previousValue = fromDate ? await this._getLastSignalValue(id) ?? void 0 : void 0;
-    const absolute = ABSOLUTE_TOLERANCE_TYPES.has(this.indicator1.type);
     const signalBars = evaluateSignal(series1, series2, this.comparison, this.tolerance, absolute, previousValue);
     const bars = signalBars.filter((b) => b.date <= latestClosed);
-    if (bars.length > 0) {
-      await this._upsertSeries(bars);
+    if (bars.length > 0) await this._upsertSeries(bars);
+  }
+  _evaluateOneBar(v1, v2, absolute, prev) {
+    if (this.tolerance === 0) {
+      switch (this.comparison) {
+        case ">":
+          return v1 > v2 ? 1 : 0;
+        case "<":
+          return v1 < v2 ? 1 : 0;
+        case "=":
+          return v1 === v2 ? 1 : 0;
+      }
+    }
+    const upper = absolute ? v2 + this.tolerance : v2 * (1 + this.tolerance / 100);
+    const lower = absolute ? v2 - this.tolerance : v2 * (1 - this.tolerance / 100);
+    if (this.comparison === "=") return v1 >= lower && v1 <= upper ? 1 : 0;
+    if (prev === void 0) {
+      return this.comparison === ">" ? v1 > v2 ? 1 : 0 : v1 < v2 ? 1 : 0;
+    }
+    if (this.comparison === ">") {
+      return prev === 1 ? v1 < lower ? 0 : 1 : v1 > upper ? 1 : 0;
     }
+    return prev === 1 ? v1 > upper ? 0 : 1 : v1 < lower ? 1 : 0;
   }
   async _upsertSeries(bars) {
     const { id } = await this.resolve();
@@ -744,19 +1059,11 @@ var SignalHandle = class _SignalHandle {
     const { id } = await this.resolve();
     return this._storage.signals.getSeries(id, range);
   }
-  withMarket(market) {
-    if (market === this._market) return this;
-    return _SignalHandle.fromResolved(this._storage, market, this.id, {
-      indicator1: this.indicator1.withMarket(market),
-      indicator2: this.indicator2.withMarket(market),
-      comparison: this.comparison,
-      tolerance: this.tolerance
-    });
-  }
   /**
-   * Compute the signal's boolean value at `date` using the given market
-   * (typically an overlay market for pre-close preview). Pure — no writes.
-   * Returns null if either indicator cannot produce a value at `date`.
+   * Compute the signal's boolean value at `date` without persisting anything,
+   * with optional live-quote `overrides` that are routed through each
+   * indicator's `computeAt`. Returns null if either indicator cannot produce
+   * a value at `date`.
    *
    * @param prevBool - The signal's boolean value at the bar immediately
    *   preceding `date`, used for hysteresis when `tolerance > 0`. If not
@@ -764,10 +1071,10 @@ var SignalHandle = class _SignalHandle {
    *   standalone callers). On the preview path `_evaluate` passes this from
    *   the in-memory `dateMap` so we never read stale storage.
    */
-  async computeAt(market, date, prevBool) {
+  async computeAt(date, overrides, prevBool) {
     const [v1, v2] = await Promise.all([
-      this.indicator1.computeAt(market, date),
-      this.indicator2.computeAt(market, date)
+      this.indicator1.computeAt(date, overrides),
+      this.indicator2.computeAt(date, overrides)
     ]);
     if (v1 === null || v2 === null) return null;
     const absolute = ABSOLUTE_TOLERANCE_TYPES.has(this.indicator1.type);
@@ -818,26 +1125,25 @@ var SignalHandle = class _SignalHandle {
   }
   /**
    * Read-only preview of the signal series with an in-memory bar at `date`
-   * computed via `computeAt` against a quote-overlay market. Does NOT write
-   * to `signals_series`.
+   * computed via `computeAt` with the supplied live-quote `overrides`. Does
+   * NOT write to `signals_series`.
    *
    * @param date - Target trading day whose boolean is computed in-memory.
-   * @param quoteOverrides - Raw (unleveraged) quotes keyed by ticker symbol.
+   * @param overrides - Raw (unleveraged) quotes keyed by market symbol.
    * @param range - Optional filter applied to the returned bars.
    */
-  async previewSeries(date, quoteOverrides, range) {
+  async previewSeries(date, overrides, range) {
     const tradingDays = await this._storage.tradingDays.getRange();
     if (!tradingDays.includes(date)) {
       throw new Error(`previewSeries: ${date} is not a trading day`);
     }
-    const overlay = createQuoteOverlay(this._market, { [date]: quoteOverrides }, { fallbackMissingQuotes: true });
     let bars = await this._querySeriesFromDb();
     const dateMap = /* @__PURE__ */ new Map();
     for (const bar of bars) dateMap.set(bar.date, bar.value === 1);
     const limitIdx = tradingDays.indexOf(date);
     const prevDate = limitIdx > 0 ? tradingDays[limitIdx - 1] : void 0;
     const prevBool = prevDate !== void 0 ? dateMap.get(prevDate) ?? null : null;
-    const todayBool = await this.computeAt(overlay, date, prevBool);
+    const todayBool = await this.computeAt(date, overrides, prevBool);
     if (todayBool !== null) {
       const numeric = todayBool ? 1 : 0;
       const idx = bars.findIndex((b) => b.date === date);
@@ -885,6 +1191,9 @@ var AllocationHandle = class _AllocationHandle {
     handle._resolvedId = id;
     return handle;
   }
+  toJSON() {
+    return this.holdings.map(([ticker, weight]) => ({ symbol: ticker.symbol, leverage: ticker.leverage, weight })).sort((a, b) => a.symbol.localeCompare(b.symbol) || a.leverage - b.leverage);
+  }
   async _doResolve() {
     await Promise.all(this.holdings.map(([ticker]) => ticker.resolve()));
     const holdingsJson = {};
@@ -1219,7 +1528,9 @@ var SimulationHandle = class {
   _lastLeveragedPrices;
   _currentLeveragedPrices;
   _lastDate;
-  constructor(series, trades, startingPortfolio, finalState) {
+  _pushedQuotes;
+  _liveEvaluator;
+  constructor(series, trades, startingPortfolio, finalState, liveEvaluator) {
     this.series = series;
     this.trades = trades;
     this.startingPortfolio = startingPortfolio;
@@ -1238,6 +1549,8 @@ var SimulationHandle = class {
       this._currentLeveragedPrices = /* @__PURE__ */ new Map();
       this._lastDate = "";
     }
+    this._pushedQuotes = {};
+    this._liveEvaluator = liveEvaluator ?? null;
   }
   push(...prices) {
     if (!this._portfolio || !this._currentAllocation) {
@@ -1272,6 +1585,48 @@ var SimulationHandle = class {
       pendingTrades: this._portfolio.trades(this._currentAllocation, priceArray, this._lastDate)
     };
   }
+  /**
+   * One-call live update. Feeds portfolio-relevant ticker prices into `push`
+   * (derived from `quotes` via the running portfolio's holdings), accumulates
+   * every symbol in `quotes` into an internal override map so macro symbols
+   * (e.g. `^VIX`) persist across ticks, then delegates to the simulation's
+   * strategy for rule / signal / indicator evaluation at `date`.
+   *
+   * Without a live evaluator attached, returns just the portfolio snapshot
+   * with allocation/rules/signals empty.
+   *
+   * @param quotes Symbol → raw live price. Portfolio tickers flow through
+   *   `push` for leveraged-equity math; non-portfolio symbols are still
+   *   layered into the overlay so indicators can see them.
+   * @param options.date Target trading day to evaluate against. Defaults to
+   *   the current UTC ISO date; callers with non-UTC semantics or after-hours
+   *   rollover should supply their own.
+   */
+  async pushAndPreview(quotes, options = {}) {
+    const priceArgs = [];
+    if (this._portfolio) {
+      const seen = /* @__PURE__ */ new Set();
+      for (const [ticker] of this._portfolio.holdings) {
+        if (ticker.symbol === "CASHX") continue;
+        if (seen.has(ticker.symbol)) continue;
+        const price = quotes[ticker.symbol];
+        if (price !== void 0) {
+          priceArgs.push([ticker, price]);
+          seen.add(ticker.symbol);
+        }
+      }
+    }
+    const snapshot = this.push(...priceArgs);
+    for (const [symbol, price] of Object.entries(quotes)) {
+      this._pushedQuotes[symbol] = price;
+    }
+    if (!this._liveEvaluator) {
+      return { snapshot, allocation: null, activeRuleIndex: -1, rules: [] };
+    }
+    const date = options.date ?? (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+    const strategyState = await this._liveEvaluator.previewLiveState(date, { ...this._pushedQuotes });
+    return { snapshot, ...strategyState };
+  }
 };
 
 // src/handles/strategy.ts
@@ -1344,6 +1699,22 @@ var StrategyHandle = class {
   get rules() {
     return this._rules;
   }
+  marketSymbols() {
+    const set = /* @__PURE__ */ new Set();
+    for (const rule of this._rules) {
+      for (const [ticker] of rule.hold.holdings) {
+        if (ticker.symbol !== "CASHX") set.add(ticker.symbol);
+      }
+      for (const signal of rule.when ?? []) {
+        for (const ind of [signal.indicator1, signal.indicator2]) {
+          if (ind.ticker !== null && ind.ticker.symbol !== "CASHX") set.add(ind.ticker.symbol);
+          if (ind.type === "VIX") set.add("^VIX");
+          if (ind.type === "VIX3M") set.add("^VIX3M");
+        }
+      }
+    }
+    return Array.from(set).sort();
+  }
   async resolve() {
     if (this._resolvedId != null) return { id: this._resolvedId };
     if (!this._resolving) {
@@ -1456,7 +1827,9 @@ var StrategyHandle = class {
       return;
     }
     if (!this._syncing) {
-      this._syncing = this._sync(latestClosed).finally(() => {
+      this._syncing = this._sync(latestClosed).catch((err) => {
+        console.warn("[sdk] strategy sync failed, using stored data:", err);
+      }).finally(() => {
         this._syncing = null;
       });
     }
@@ -1466,7 +1839,7 @@ var StrategyHandle = class {
   }
   async _sync(latestClosed) {
     const { id } = await this.resolve();
-    const { entries } = await this._evaluate(this._market, latestClosed);
+    const { entries } = await this._evaluate(latestClosed);
     if (entries.length > 0) {
       await this._storage.strategies.writeSeries(id, entries);
     }
@@ -1474,26 +1847,98 @@ var StrategyHandle = class {
   /**
    * Pure evaluate — runs the same pipeline as _sync but returns the computed
    * evaluation instead of persisting. Used by both _sync (post-close write
-   * path) and previewAllocation (pre-close read-only path).
+   * path) and the public preview methods (pre-close read-only path).
+   *
+   * When `overrides` is `undefined` we take the write path — syncing signals
+   * through storage as normal. When `overrides` is provided (even an empty
+   * map) we take the read-only preview path: historical signal bars come
+   * straight from storage, today's bar is computed in-memory via
+   * `signal.computeAt(date, overrides, prevBool)`, and nothing is written.
    *
-   * The `market === this._market` identity check is what distinguishes the two
-   * paths: when they are the same object the method takes the write path (syncing
-   * signals through storage as normal); when they differ it takes the read-only
-   * preview path (historical bars from storage, today's value computed in-memory
-   * via `computeAt`). Callers that want the preview path must therefore supply a
-   * *different* market object — for example one produced by `createQuoteOverlay`.
+   * Incremental path: when a strategy checkpoint exists (`getLatestSeriesDate`
+   * returns non-null), only the window (lastDate, limitDate] is processed.
+   * The current allocation is carried forward from `getLatestAllocationId`.
+   * Bootstrap: when no checkpoint exists, falls back to `_evaluateCold` which
+   * runs the full-history evaluation.
    */
-  async _evaluate(market, limitDate) {
+  async _evaluate(limitDate, overrides) {
+    const { id } = await this.resolve();
+    const lastDate = await this._storage.strategies.getLatestSeriesDate(id);
+    const tradingDays = await this._storage.tradingDays.getRange();
+    const limitIdx = tradingDays.indexOf(limitDate);
+    const allocations = [];
+    const allocIndexMap = /* @__PURE__ */ new Map();
+    const rulesInput = this._rules.map((rule) => {
+      let allocIdx = allocIndexMap.get(rule.hold.id);
+      if (allocIdx === void 0) {
+        allocIdx = allocations.length;
+        allocations.push(rule.hold);
+        allocIndexMap.set(rule.hold.id, allocIdx);
+      }
+      return {
+        signalIds: (rule.when ?? []).map((s) => s.id),
+        allocationIndex: allocIdx
+      };
+    });
+    if (lastDate === null) {
+      return this._evaluateCold(limitDate, overrides, rulesInput, allocations, tradingDays);
+    }
+    const lastAllocId = await this._storage.strategies.getLatestAllocationId(id);
+    const incrementalStartIdx = tradingDays.indexOf(lastDate) + 1;
+    const incrementalDays = tradingDays.slice(incrementalStartIdx, limitIdx + 1);
+    const isOverrideRefresh = incrementalDays.length === 0 && overrides !== void 0 && limitDate === lastDate;
+    const newDays = isOverrideRefresh ? [limitDate] : incrementalDays;
+    const startIdx = isOverrideRefresh ? limitIdx : incrementalStartIdx;
+    if (newDays.length === 0) return { allocations, entries: [] };
     const allSignals = /* @__PURE__ */ new Set();
-    for (const rule of this._rules) {
-      if (rule.when) rule.when.forEach((s) => allSignals.add(s));
+    for (const rule of this._rules) if (rule.when) rule.when.forEach((s) => allSignals.add(s));
+    const signalSeries = /* @__PURE__ */ new Map();
+    await Promise.all(
+      Array.from(allSignals).map(async (signal) => {
+        const bars = overrides === void 0 ? await signal.series({ from: newDays[0], to: limitDate }) : await this._storage.signals.getSeries(signal.id, { from: newDays[0], to: limitDate });
+        const dateMap = /* @__PURE__ */ new Map();
+        for (const bar of bars) dateMap.set(bar.date, bar.value === 1);
+        if (overrides !== void 0) {
+          const prevDateIdx = startIdx - 1 >= 0 ? tradingDays[startIdx - 1] : void 0;
+          const prevBool = prevDateIdx !== void 0 ? await signal.value(prevDateIdx) === 1 : null;
+          const todayValue = await signal.computeAt(limitDate, overrides, prevBool);
+          if (todayValue !== null) dateMap.set(limitDate, todayValue);
+        }
+        signalSeries.set(signal.id, dateMap);
+      })
+    );
+    const rebalanceDates = computeRebalanceDates(tradingDays, this._freq, this._offset);
+    const entries = [];
+    let current = lastAllocId !== null ? allocIndexMap.get(lastAllocId) ?? void 0 : void 0;
+    for (const date of newDays) {
+      if (rebalanceDates.has(date)) {
+        for (const rule of rulesInput) {
+          if (rule.signalIds.length === 0) {
+            current = rule.allocationIndex;
+            break;
+          }
+          const allTrue = rule.signalIds.every((sid) => signalSeries.get(sid)?.get(date) ?? false);
+          if (allTrue) {
+            current = rule.allocationIndex;
+            break;
+          }
+        }
+      }
+      if (current !== void 0) {
+        entries.push({ date, allocationId: allocations[current].id });
+      }
     }
+    return { allocations, entries };
+  }
+  // Renamed body of the old _evaluate — used only for first-ever evaluate (bootstrap).
+  async _evaluateCold(limitDate, overrides, rulesInput, allocations, tradingDays) {
+    const allSignals = /* @__PURE__ */ new Set();
+    for (const rule of this._rules) if (rule.when) rule.when.forEach((s) => allSignals.add(s));
     const signalSeries = /* @__PURE__ */ new Map();
-    const tradingDays = await this._storage.tradingDays.getRange();
-    if (market === this._market) {
+    if (overrides === void 0) {
       await Promise.all(
         Array.from(allSignals).map(async (signal) => {
-          const bars = await signal.withMarket(market).series();
+          const bars = await signal.series();
           const dateMap = /* @__PURE__ */ new Map();
           for (const bar of bars) dateMap.set(bar.date, bar.value === 1);
           signalSeries.set(signal.id, dateMap);
@@ -1508,7 +1953,7 @@ var StrategyHandle = class {
           const dateMap = /* @__PURE__ */ new Map();
           for (const bar of historicalBars) dateMap.set(bar.date, bar.value === 1);
           const prevBool = prevDate !== void 0 ? dateMap.get(prevDate) ?? null : null;
-          const todayValue = await signal.computeAt(market, limitDate, prevBool);
+          const todayValue = await signal.computeAt(limitDate, overrides, prevBool);
           if (todayValue !== null) {
             dateMap.set(limitDate, todayValue);
           }
@@ -1517,20 +1962,6 @@ var StrategyHandle = class {
       );
     }
     const rebalanceDates = computeRebalanceDates(tradingDays, this._freq, this._offset);
-    const allocations = [];
-    const allocIndexMap = /* @__PURE__ */ new Map();
-    const rulesInput = this._rules.map((rule) => {
-      let allocIdx = allocIndexMap.get(rule.hold.id);
-      if (allocIdx === void 0) {
-        allocIdx = allocations.length;
-        allocations.push(rule.hold);
-        allocIndexMap.set(rule.hold.id, allocIdx);
-      }
-      return {
-        signalIds: (rule.when ?? []).map((s) => s.id),
-        allocationIndex: allocIdx
-      };
-    });
     const evalResult = evaluateStrategy(signalSeries, rulesInput, rebalanceDates, tradingDays);
     const entries = Array.from(evalResult.entries()).filter(([date]) => date <= limitDate).map(([date, allocIdx]) => ({ date, allocationId: allocations[allocIdx].id }));
     return { allocations, entries };
@@ -1584,7 +2015,10 @@ var StrategyHandle = class {
       closePrices,
       leveragedPrices
     };
-    return new SimulationHandle(result.series, result.trades, options.portfolio, finalState);
+    const liveEvaluator = {
+      previewLiveState: (date, overrides) => this.previewLiveState(date, overrides)
+    };
+    return new SimulationHandle(result.series, result.trades, options.portfolio, finalState, liveEvaluator);
   }
   /**
    * Preview the allocation this strategy would produce for `date` if today
@@ -1592,20 +2026,19 @@ var StrategyHandle = class {
    * signals_series, or indicators_series. Safe to call before market close.
    *
    * @param date - The trading day to preview (must be in tradingDays.getRange()).
-   * @param quoteOverrides - Raw (unleveraged) live prices keyed by ticker symbol.
-   *   Symbols absent from this map will fall back to yesterday's close via the
-   *   quote overlay.
+   * @param overrides - Raw (unleveraged) live prices keyed by market symbol.
+   *   Symbols absent from this map fall back to the last stored value
+   *   (see `IndicatorHandle._resolveRawBars`).
    * @returns The AllocationHandle for `date`, or null if the strategy has no
    *   evaluable entry for that date.
    */
-  async previewAllocation(date, quoteOverrides) {
+  async previewAllocation(date, overrides) {
     await this.resolve();
     const tradingDays = await this._storage.tradingDays.getRange();
     if (!tradingDays.includes(date)) {
       throw new Error(`previewAllocation: ${date} is not a trading day`);
     }
-    const overlayMarket = createQuoteOverlay(this._market, { [date]: quoteOverrides }, { fallbackMissingQuotes: true });
-    const { allocations, entries } = await this._evaluate(overlayMarket, date);
+    const { allocations, entries } = await this._evaluate(date, overrides);
     const target = entries.find((e) => e.date === date);
     if (!target) return null;
     const alloc = allocations.find((a) => a.id === target.allocationId);
@@ -1614,27 +2047,45 @@ var StrategyHandle = class {
   /**
    * Read-only preview of the strategy's allocation series including `date`.
    * Returns stored historical allocations plus an in-memory bar at `date`
-   * computed via the same overlay path as `previewAllocation`.
+   * computed via the same overrides-based preview path as `previewAllocation`.
    *
-   * @param date - Target trading day to splice in-memory via overlay market.
-   * @param quoteOverrides - Raw (unleveraged) quotes keyed by ticker symbol.
+   * @param date - Target trading day to splice in-memory.
+   * @param overrides - Raw (unleveraged) quotes keyed by market symbol.
    * @param range - Optional filter applied to the returned bars.
    */
-  async previewSeries(date, quoteOverrides, range) {
+  async previewSeries(date, overrides, range) {
     await this.resolve();
     const tradingDays = await this._storage.tradingDays.getRange();
     if (!tradingDays.includes(date)) {
       throw new Error(`previewSeries: ${date} is not a trading day`);
     }
-    const overlayMarket = createQuoteOverlay(this._market, { [date]: quoteOverrides }, { fallbackMissingQuotes: true });
-    const { allocations, entries } = await this._evaluate(overlayMarket, date);
+    const { allocations, entries } = await this._evaluate(date, overrides);
     const allocById = /* @__PURE__ */ new Map();
     for (const a of allocations) allocById.set(a.id, a);
-    for (const [id, a] of this._allocationMap) if (!allocById.has(id)) allocById.set(id, a);
-    let bars = entries.map((e) => ({
+    for (const [id2, a] of this._allocationMap) if (!allocById.has(id2)) allocById.set(id2, a);
+    const { id } = await this.resolve();
+    const lastDate = await this._storage.strategies.getLatestSeriesDate(id);
+    let storedBars = [];
+    if (lastDate !== null && entries.length > 0 && entries[0].date > (tradingDays[0] ?? "")) {
+      const storedEntries = await this._storage.strategies.getSeries(id, { to: lastDate });
+      storedBars = storedEntries.map((e) => ({
+        date: e.date,
+        allocation: allocById.get(e.allocationId) ?? this._allocationMap.get(e.allocationId)
+      }));
+    } else if (lastDate !== null && entries.length === 0) {
+      const storedEntries = await this._storage.strategies.getSeries(id);
+      storedBars = storedEntries.map((e) => ({
+        date: e.date,
+        allocation: allocById.get(e.allocationId) ?? this._allocationMap.get(e.allocationId)
+      }));
+    }
+    const newBars = entries.map((e) => ({
       date: e.date,
       allocation: allocById.get(e.allocationId)
     }));
+    const newDates = new Set(newBars.map((b) => b.date));
+    let bars = [...storedBars.filter((b) => !newDates.has(b.date)), ...newBars];
+    bars.sort((a, b) => a.date.localeCompare(b.date));
     if (range) {
       bars = bars.filter(
         (b) => (range.from === void 0 || b.date >= range.from) && (range.to === void 0 || b.date <= range.to)
@@ -1642,6 +2093,70 @@ var StrategyHandle = class {
     }
     return bars;
   }
+  /**
+   * Full live strategy view at `date` under live-quote `overrides`: the active
+   * allocation, the index of the rule that fired (or fallback), and per-rule
+   * per-signal indicator values + truth. Computed entirely through the
+   * overrides preview path — no writes to any `*_series` tables.
+   *
+   * Threshold indicators have their date suppressed (`null`) since their
+   * synthetic series runs over every trading day in storage including future
+   * dates and would report a far-future date for the last bar.
+   */
+  async previewLiveState(date, overrides) {
+    await this.resolve();
+    const tradingDays = await this._storage.tradingDays.getRange();
+    if (!tradingDays.includes(date)) {
+      throw new Error(`previewLiveState: ${date} is not a trading day`);
+    }
+    const [{ allocations, entries }, rules] = await Promise.all([
+      this._evaluate(date, overrides),
+      Promise.all(
+        this._rules.map(async (rule) => {
+          const signalHandles = rule.when ?? [];
+          const signals = await Promise.all(
+            signalHandles.map(async (sig) => {
+              const [i1Series, i2Series, sigSeries] = await Promise.all([
+                sig.indicator1.previewSeries(date, overrides),
+                sig.indicator2.previewSeries(date, overrides),
+                sig.previewSeries(date, overrides)
+              ]);
+              const last1 = i1Series.at(-1);
+              const last2 = i2Series.at(-1);
+              const lastSig = sigSeries.at(-1);
+              const i1IsThreshold = sig.indicator1.type === "Threshold";
+              const i2IsThreshold = sig.indicator2.type === "Threshold";
+              return {
+                indicator1: {
+                  value: last1?.value ?? null,
+                  date: i1IsThreshold ? null : last1?.date ?? null
+                },
+                indicator2: {
+                  value: last2?.value ?? null,
+                  date: i2IsThreshold ? null : last2?.date ?? null
+                },
+                isTrue: lastSig?.value === 1
+              };
+            })
+          );
+          return { signals };
+        })
+      )
+    ]);
+    const target = entries.find((e) => e.date === date);
+    const allocation = target ? allocations.find((a) => a.id === target.allocationId) ?? this._allocationMap.get(target.allocationId) ?? null : null;
+    const fallbackIndex = this._rules.length - 1;
+    let activeRuleIndex = fallbackIndex;
+    if (target) {
+      for (let r = 0; r < this._rules.length; r++) {
+        if (this._rules[r].hold.id === target.allocationId) {
+          activeRuleIndex = r;
+          break;
+        }
+      }
+    }
+    return { allocation, activeRuleIndex, rules };
+  }
   async _fetchPricesForTickers(bars, from, to) {
     const tickerMap = /* @__PURE__ */ new Map();
     for (const bar of bars) {
@@ -1766,6 +2281,21 @@ function createClient(options) {
     strategy: (optionsOrLinkId) => new StrategyHandle(storage, market, optionsOrLinkId)
   };
 }
+
+// src/handles/allocation-equality.ts
+function allocationsEqual(a, b) {
+  if (a === null && b === null) return true;
+  if (a === null || b === null) return false;
+  const aj = a.toJSON();
+  const bj = b.toJSON();
+  if (aj.length !== bj.length) return false;
+  for (let i = 0; i < aj.length; i++) {
+    if (aj[i].symbol !== bj[i].symbol) return false;
+    if (aj[i].leverage !== bj[i].leverage) return false;
+    if (Math.abs(aj[i].weight - bj[i].weight) > 1e-9) return false;
+  }
+  return true;
+}
 export {
   AllocationHandle,
   IndicatorHandle,
@@ -1774,6 +2304,8 @@ export {
   SimulationHandle,
   StrategyHandle,
   TickerHandle,
+  allocationsEqual,
+  computeRebalanceDates,
   createClient
 };
 //# sourceMappingURL=index.js.map