@livefolio/sdk 0.3.2 → 0.3.3

package/dist/index.js

@@ -238,35 +238,19 @@ 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;
-    }
-  };
-}
-
 // 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 +321,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;
       });
     }
@@ -401,7 +395,16 @@ var IndicatorHandle = class _IndicatorHandle {
     if (info.provider !== "computed") {
       bars = await this._applyLeverage(bars, fromDate);
     }
-    bars = bars.filter((b) => b.date <= latestClosed);
+    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];
+    }
+    bars = bars.filter((b) => b.date <= horizon);
     if (bars.length > 0) {
       await this._upsertSeries(bars);
     }
@@ -414,17 +417,6 @@ var IndicatorHandle = class _IndicatorHandle {
     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 +450,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).
+   *
+   * 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 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.
+   * 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 +476,16 @@ 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);
+      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 +494,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 +511,81 @@ 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 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 +608,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 +728,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;
@@ -716,7 +794,9 @@ var SignalHandle = class _SignalHandle {
       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] signal sync failed, using stored data:", err);
+      }).finally(() => {
         this._syncing = null;
       });
     }
@@ -744,19 +824,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 +836,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 +890,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);
@@ -1219,7 +1290,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 +1311,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 +1347,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
@@ -1456,7 +1573,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 +1585,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 +1593,25 @@ 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).
    *
-   * 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`.
+   * 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.
    */
-  async _evaluate(market, limitDate) {
+  async _evaluate(limitDate, overrides) {
     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 +1626,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);
           }
@@ -1584,7 +1702,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 +1713,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,20 +1734,19 @@ 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);
@@ -1642,6 +1761,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) {