@livefolio/sdk 0.3.0 → 0.3.2

package/dist/index.js

@@ -45,14 +45,40 @@ var FRED_SERIES = {
   T20Y: "DGS20",
   T30Y: "DGS30"
 };
+var RATE_TICKER_SYMBOLS = /* @__PURE__ */ new Set([
+  "DTB3",
+  "DTB6",
+  "DFF",
+  "DGS3MO",
+  "DGS6MO",
+  "DGS1",
+  "DGS2",
+  "DGS3",
+  "DGS5",
+  "DGS7",
+  "DGS10",
+  "DGS20",
+  "DGS30"
+]);
 var COMPUTED_TYPES = /* @__PURE__ */ new Set(["SMA", "EMA", "RSI", "Return", "Volatility", "Drawdown"]);
 var CALENDAR_TYPES = /* @__PURE__ */ new Set(["Month", "Day of Week", "Day of Month", "Day of Year"]);
+function isRateTickerSymbol(symbol) {
+  return symbol != null && RATE_TICKER_SYMBOLS.has(symbol);
+}
 function getProviderInfo(type, tickerSymbol) {
-  if (type === "Price") return { provider: "yahoo", symbol: tickerSymbol };
+  if (type === "Price") {
+    const info = { provider: "yahoo", symbol: tickerSymbol };
+    if (isRateTickerSymbol(tickerSymbol)) info.rateSeries = true;
+    return info;
+  }
   if (type === "VIX") return { provider: "yahoo", symbol: "^VIX" };
   if (type === "VIX3M") return { provider: "yahoo", symbol: "^VIX3M" };
-  if (type in FRED_SERIES) return { provider: "fred", seriesId: FRED_SERIES[type] };
-  if (COMPUTED_TYPES.has(type)) return { provider: "computed", dependsOn: "Price", symbol: tickerSymbol };
+  if (type in FRED_SERIES) return { provider: "fred", seriesId: FRED_SERIES[type], rateSeries: true };
+  if (COMPUTED_TYPES.has(type)) {
+    const info = { provider: "computed", dependsOn: "Price", symbol: tickerSymbol };
+    if (isRateTickerSymbol(tickerSymbol)) info.rateSeries = true;
+    return info;
+  }
   if (CALENDAR_TYPES.has(type)) return { provider: "calendar" };
   return { provider: "none" };
 }
@@ -123,14 +149,14 @@ function computeRsi(bars, lookback) {
 }
 
 // src/computations/returns.ts
-function computeReturns(bars, lookback) {
+function computeReturns(bars, lookback, mode = "pct") {
   if (bars.length <= lookback) return [];
   const result = [];
   for (let i = lookback; i < bars.length; i++) {
-    result.push({
-      date: bars[i].date,
-      value: (bars[i].value - bars[i - lookback].value) / bars[i - lookback].value
-    });
+    const curr = bars[i].value;
+    const prev = bars[i - lookback].value;
+    const value = mode === "abs" ? curr - prev : (curr - prev) / prev;
+    result.push({ date: bars[i].date, value });
   }
   return result;
 }
@@ -212,7 +238,40 @@ 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
+function _subtractCalendarDays(date, days) {
+  const d = new Date(date);
+  d.setUTCDate(d.getUTCDate() - days);
+  return d.toISOString().slice(0, 10);
+}
 var IndicatorHandle = class _IndicatorHandle {
   type;
   ticker;
@@ -315,9 +374,13 @@ var IndicatorHandle = class _IndicatorHandle {
         });
         await priceHandle._ensureFresh();
         const priceBars = await priceHandle._querySeriesFromDb();
-        const computeFn = getComputation(this.type);
-        if (!computeFn) throw new Error(`No computation found for type "${this.type}"`);
-        bars = computeFn(priceBars, this.lookback);
+        if (this.type === "Return") {
+          bars = computeReturns(priceBars, this.lookback, info.rateSeries ? "abs" : "pct");
+        } else {
+          const computeFn = getComputation(this.type);
+          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);
         }
@@ -335,22 +398,8 @@ var IndicatorHandle = class _IndicatorHandle {
       case "none":
         return;
     }
-    const leverage = this.ticker?.leverage ?? 1;
-    if (leverage !== 1 && info.provider !== "computed" && bars.length > 0) {
-      let anchor;
-      if (fromDate) {
-        const lastStored = await this._storage.indicators.getValue(this._resolvedId, fromDate);
-        anchor = lastStored ?? bars[0].value;
-      } else {
-        anchor = bars[0].value;
-      }
-      const leveraged = [{ date: bars[0].date, value: anchor }];
-      for (let i = 1; i < bars.length; i++) {
-        const dailyReturn = (bars[i].value - bars[i - 1].value) / bars[i - 1].value;
-        const prev = leveraged[i - 1].value;
-        leveraged.push({ date: bars[i].date, value: prev * (1 + leverage * dailyReturn) });
-      }
-      bars = leveraged;
+    if (info.provider !== "computed") {
+      bars = await this._applyLeverage(bars, fromDate);
     }
     bars = bars.filter((b) => b.date <= latestClosed);
     if (bars.length > 0) {
@@ -365,6 +414,103 @@ 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
+   * consistent.
+   *
+   * `anchorDate` is the date of the last *already-stored* leveraged bar
+   * (i.e., the bar just before `rawBars[0]`). The stored leveraged value
+   * at that date becomes `leveraged[0]`; raw returns are then compounded
+   * forward for each subsequent bar.
+   *
+   * If no stored anchor exists (first-ever sync), falls back to rawBars[0]
+   * as the starting raw value — identical to `_sync`'s behaviour.
+   */
+  async _applyLeverage(rawBars, anchorDate) {
+    const leverage = this.ticker?.leverage ?? 1;
+    if (leverage === 1 || rawBars.length === 0) return rawBars;
+    if (isRateTickerSymbol(this.ticker?.symbol ?? null)) return rawBars;
+    let anchor;
+    if (anchorDate) {
+      const lastStored = await this._storage.indicators.getValue(this._resolvedId, anchorDate);
+      anchor = lastStored ?? rawBars[0].value;
+    } else {
+      anchor = rawBars[0].value;
+    }
+    const leveraged = [{ date: rawBars[0].date, value: anchor }];
+    for (let i = 1; i < rawBars.length; i++) {
+      const dailyReturn = (rawBars[i].value - rawBars[i - 1].value) / rawBars[i - 1].value;
+      const prev = leveraged[i - 1].value;
+      leveraged.push({ date: rawBars[i].date, value: prev * (1 + leverage * dailyReturn) });
+    }
+    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.
+   *
+   * 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.
+   */
+  async computeAt(market, date) {
+    if (this.type === "Threshold") return this.threshold;
+    const tickerSymbol = this.ticker?.symbol ?? null;
+    const info = getProviderInfo(this.type, tickerSymbol);
+    if (info.provider === "none") return null;
+    if (info.provider === "calendar") {
+      const allDays = await this._storage.tradingDays.getRange();
+      const dayBars = allDays.map((d) => ({ date: d, value: 0 }));
+      const computed = computeCalendar(dayBars, this.type);
+      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 anchorDate = rawBars2.length > 0 ? rawBars2[0].date : void 0;
+      const priceBars = await this._applyLeverage(rawBars2, anchorDate);
+      const computeFn = getComputation(this.type);
+      if (!computeFn) throw new Error(`No computation found for type "${this.type}"`);
+      const computed = computeFn(priceBars, this.lookback);
+      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 leverage = this.ticker?.leverage ?? 1;
+    if (leverage === 1) {
+      return rawBars.find((b) => b.date === date)?.value ?? null;
+    }
+    const dateIdx = rawBars.findIndex((b) => b.date === date);
+    if (dateIdx < 0) return null;
+    const prevBar = rawBars[dateIdx - 1];
+    if (!prevBar) {
+      return rawBars[dateIdx].value;
+    }
+    const storedPrev = await this._storage.indicators.getValue(this._resolvedId, prevBar.date);
+    const leveragedPrev = storedPrev ?? prevBar.value;
+    const rawReturn = (rawBars[dateIdx].value - prevBar.value) / prevBar.value;
+    return leveragedPrev * (1 + leverage * rawReturn);
+  }
   // ── Public data access ─────────────────────────────────────────────
   async series(range) {
     if (this.type === "Threshold") {
@@ -386,6 +532,46 @@ var IndicatorHandle = class _IndicatorHandle {
     const { id } = await this.resolve();
     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
+   * 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 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) {
+    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 (range) {
+      bars = bars.filter(
+        (b) => (range.from === void 0 || b.date >= range.from) && (range.to === void 0 || b.date <= range.to)
+      );
+    }
+    return bars;
+  }
 };
 
 // src/computations/signal.ts
@@ -558,6 +744,61 @@ 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`.
+   *
+   * @param prevBool - The signal's boolean value at the bar immediately
+   *   preceding `date`, used for hysteresis when `tolerance > 0`. If not
+   *   provided, falls back to `storage.signals.getLastValue` (suitable for
+   *   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) {
+    const [v1, v2] = await Promise.all([
+      this.indicator1.computeAt(market, date),
+      this.indicator2.computeAt(market, date)
+    ]);
+    if (v1 === null || v2 === null) return null;
+    const absolute = ABSOLUTE_TOLERANCE_TYPES.has(this.indicator1.type);
+    if (this.tolerance === 0) {
+      switch (this.comparison) {
+        case ">":
+          return v1 > v2;
+        case "<":
+          return v1 < v2;
+        case "=":
+          return v1 === v2;
+      }
+    }
+    const tolerance = this.tolerance;
+    const upper = absolute ? v2 + tolerance : v2 * (1 + tolerance / 100);
+    const lower = absolute ? v2 - tolerance : v2 * (1 - tolerance / 100);
+    if (this.comparison === "=") {
+      return v1 >= lower && v1 <= upper;
+    }
+    let resolvedPrevBool;
+    if (prevBool !== void 0 && prevBool !== null) {
+      resolvedPrevBool = prevBool;
+    } else {
+      const prev = await this._storage.signals.getLastValue(this.id);
+      resolvedPrevBool = prev === 1;
+    }
+    if (this.comparison === ">") {
+      return resolvedPrevBool ? v1 >= lower : v1 > upper;
+    }
+    return resolvedPrevBool ? v1 <= upper : v1 < lower;
+  }
   // ── Public data access ─────────────────────────────────────────────
   async series(range) {
     await this._ensureFresh();
@@ -575,6 +816,44 @@ var SignalHandle = class _SignalHandle {
     const { id } = await this.resolve();
     return this._storage.signals.getLastValue(id);
   }
+  /**
+   * 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`.
+   *
+   * @param date - Target trading day whose boolean is computed in-memory.
+   * @param quoteOverrides - Raw (unleveraged) quotes keyed by ticker symbol.
+   * @param range - Optional filter applied to the returned bars.
+   */
+  async previewSeries(date, quoteOverrides, 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);
+    if (todayBool !== null) {
+      const numeric = todayBool ? 1 : 0;
+      const idx = bars.findIndex((b) => b.date === date);
+      if (idx >= 0) {
+        bars[idx] = { date, value: numeric };
+      } else {
+        bars = [...bars, { date, value: numeric }].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)
+      );
+    }
+    return bars;
+  }
 };
 
 // src/handles/allocation.ts
@@ -698,15 +977,12 @@ var PortfolioHandle = class {
   holdings;
   constructor(holdings) {
     const seen = /* @__PURE__ */ new Set();
-    for (const [ticker, quantity] of holdings) {
+    for (const [ticker] of holdings) {
       const key = `${ticker.symbol}:${ticker.leverage}`;
       if (seen.has(key)) {
         throw new Error(`Duplicate ticker: ${ticker.symbol}`);
       }
       seen.add(key);
-      if (quantity < 0) {
-        throw new Error(`Quantity for ${ticker.symbol} is negative: ${quantity}`);
-      }
     }
     this.holdings = holdings;
   }
@@ -719,6 +995,7 @@ var PortfolioHandle = class {
   }
   _priceFor(ticker, priceMap) {
     if (ticker.symbol === "CASHX") return 1;
+    if (isRateTickerSymbol(ticker.symbol)) return 1;
     const key = `${ticker.symbol}:${ticker.leverage}`;
     const price = priceMap.get(key);
     if (price == null) {
@@ -799,6 +1076,26 @@ var EPSILON = 1e-8;
 function tkey(symbol, leverage) {
   return `${symbol}:${leverage}`;
 }
+function symbolFromKey(key) {
+  const idx = key.lastIndexOf(":");
+  return idx === -1 ? key : key.slice(0, idx);
+}
+function isRateKey(key) {
+  return isRateTickerSymbol(symbolFromKey(key));
+}
+function navPriceForKey(key, date, prices, lastPrice) {
+  if (isRateKey(key)) return 1;
+  const live = prices[key]?.[date];
+  if (live != null) {
+    lastPrice[key] = live;
+    return live;
+  }
+  return lastPrice[key];
+}
+function daysBetween(prevIsoDate, currIsoDate) {
+  const ms = Date.UTC(Number(currIsoDate.slice(0, 4)), Number(currIsoDate.slice(5, 7)) - 1, Number(currIsoDate.slice(8, 10))) - Date.UTC(Number(prevIsoDate.slice(0, 4)), Number(prevIsoDate.slice(5, 7)) - 1, Number(prevIsoDate.slice(8, 10)));
+  return Math.round(ms / (1e3 * 60 * 60 * 24));
+}
 function runSimulation(bars, prices, rebalanceDates, portfolio) {
   const positions = {};
   const lastPrice = {};
@@ -813,15 +1110,24 @@ function runSimulation(bars, prices, rebalanceDates, portfolio) {
   const series = [];
   const trades = [];
   function valuationPrice(key, date) {
-    const live = prices[key]?.[date];
-    if (live != null) {
-      lastPrice[key] = live;
-      return live;
-    }
-    return lastPrice[key];
+    return navPriceForKey(key, date, prices, lastPrice);
   }
+  let prevDate = null;
   for (const bar of bars) {
     const date = bar.date;
+    if (prevDate != null) {
+      const days = daysBetween(prevDate, date);
+      if (days > 0) {
+        for (const [key, shares] of Object.entries(positions)) {
+          if (!isRateKey(key)) continue;
+          const ratePct = prices[key]?.[prevDate];
+          if (ratePct == null) continue;
+          const leverage = Number(key.slice(key.lastIndexOf(":") + 1)) || 1;
+          const factor = 1 + leverage * (ratePct / 100) * (days / 360);
+          positions[key] = shares * factor;
+        }
+      }
+    }
     if (rebalanceDates.has(date)) {
       let portfolioValue = cash;
       for (const [key, shares] of Object.entries(positions)) {
@@ -834,8 +1140,14 @@ function runSimulation(bars, prices, rebalanceDates, portfolio) {
       }
       const allKeys = /* @__PURE__ */ new Set([...Object.keys(positions), ...Object.keys(targetWeights)]);
       for (const key of allKeys) {
-        const price = prices[key]?.[date];
-        if (price == null || price <= 0) continue;
+        let price;
+        if (isRateKey(key)) {
+          price = 1;
+        } else {
+          const live = prices[key]?.[date];
+          if (live == null || live <= 0) continue;
+          price = live;
+        }
         const currentShares = positions[key] ?? 0;
         const targetValue = portfolioValue * (targetWeights[key] ?? 0);
         const targetShares = targetValue / price;
@@ -863,6 +1175,7 @@ function runSimulation(bars, prices, rebalanceDates, portfolio) {
       if (price != null) value += shares * price;
     }
     series.push({ date, value });
+    prevDate = date;
   }
   const finalHoldings = [];
   const tickerByKey = /* @__PURE__ */ new Map();
@@ -1153,20 +1466,56 @@ var StrategyHandle = class {
   }
   async _sync(latestClosed) {
     const { id } = await this.resolve();
-    const signalSeries = /* @__PURE__ */ new Map();
+    const { entries } = await this._evaluate(this._market, latestClosed);
+    if (entries.length > 0) {
+      await this._storage.strategies.writeSeries(id, entries);
+    }
+  }
+  /**
+   * 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).
+   *
+   * 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`.
+   */
+  async _evaluate(market, limitDate) {
     const allSignals = /* @__PURE__ */ new Set();
     for (const rule of this._rules) {
       if (rule.when) rule.when.forEach((s) => allSignals.add(s));
     }
-    await Promise.all(
-      Array.from(allSignals).map(async (signal) => {
-        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);
-      })
-    );
+    const signalSeries = /* @__PURE__ */ new Map();
     const tradingDays = await this._storage.tradingDays.getRange();
+    if (market === this._market) {
+      await Promise.all(
+        Array.from(allSignals).map(async (signal) => {
+          const bars = await signal.withMarket(market).series();
+          const dateMap = /* @__PURE__ */ new Map();
+          for (const bar of bars) dateMap.set(bar.date, bar.value === 1);
+          signalSeries.set(signal.id, dateMap);
+        })
+      );
+    } else {
+      const limitIdx = tradingDays.indexOf(limitDate);
+      const prevDate = limitIdx > 0 ? tradingDays[limitIdx - 1] : void 0;
+      await Promise.all(
+        Array.from(allSignals).map(async (signal) => {
+          const historicalBars = await this._storage.signals.getSeries(signal.id);
+          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);
+          if (todayValue !== null) {
+            dateMap.set(limitDate, todayValue);
+          }
+          signalSeries.set(signal.id, dateMap);
+        })
+      );
+    }
     const rebalanceDates = computeRebalanceDates(tradingDays, this._freq, this._offset);
     const allocations = [];
     const allocIndexMap = /* @__PURE__ */ new Map();
@@ -1183,13 +1532,8 @@ var StrategyHandle = class {
       };
     });
     const evalResult = evaluateStrategy(signalSeries, rulesInput, rebalanceDates, tradingDays);
-    const entries = Array.from(evalResult.entries()).filter(([date]) => date <= latestClosed).map(([date, allocIdx]) => ({
-      date,
-      allocationId: allocations[allocIdx].id
-    }));
-    if (entries.length > 0) {
-      await this._storage.strategies.writeSeries(id, entries);
-    }
+    const entries = Array.from(evalResult.entries()).filter(([date]) => date <= limitDate).map(([date, allocIdx]) => ({ date, allocationId: allocations[allocIdx].id }));
+    return { allocations, entries };
   }
   async _querySeriesFromDb(range) {
     const { id } = await this.resolve();
@@ -1242,6 +1586,62 @@ var StrategyHandle = class {
     };
     return new SimulationHandle(result.series, result.trades, options.portfolio, finalState);
   }
+  /**
+   * Preview the allocation this strategy would produce for `date` if today
+   * closed at the provided raw quote prices. Does NOT write to strategies_series,
+   * 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.
+   * @returns The AllocationHandle for `date`, or null if the strategy has no
+   *   evaluable entry for that date.
+   */
+  async previewAllocation(date, quoteOverrides) {
+    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 target = entries.find((e) => e.date === date);
+    if (!target) return null;
+    const alloc = allocations.find((a) => a.id === target.allocationId);
+    return alloc ?? this._allocationMap.get(target.allocationId) ?? null;
+  }
+  /**
+   * 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`.
+   *
+   * @param date - Target trading day to splice in-memory via overlay market.
+   * @param quoteOverrides - Raw (unleveraged) quotes keyed by ticker symbol.
+   * @param range - Optional filter applied to the returned bars.
+   */
+  async previewSeries(date, quoteOverrides, 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 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) => ({
+      date: e.date,
+      allocation: allocById.get(e.allocationId)
+    }));
+    if (range) {
+      bars = bars.filter(
+        (b) => (range.from === void 0 || b.date >= range.from) && (range.to === void 0 || b.date <= range.to)
+      );
+    }
+    return bars;
+  }
   async _fetchPricesForTickers(bars, from, to) {
     const tickerMap = /* @__PURE__ */ new Map();
     for (const bar of bars) {