@livefolio/sdk 0.3.2 → 0.3.4

package/dist/index.d.ts

@@ -112,9 +112,9 @@ declare class IndicatorHandle {
     private _getLatestSeriesDate;
     private _ensureFresh;
     private _sync;
+    private _fetchRawBarsForIncremental;
     private _upsertSeries;
     private _querySeriesFromDb;
-    withMarket(market: MarketProvider): IndicatorHandle;
     /**
      * Apply leverage compounding to a raw bar series, anchored to a stored
      * leveraged value. Used by both `_sync` and `computeAt` so they stay
@@ -130,37 +130,72 @@ declare class IndicatorHandle {
      */
     private _applyLeverage;
     /**
-     * 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.
+     */
+    computeAt(date: string, overrides?: Record<string, number>): Promise<number | null>;
+    /**
+     * 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.
+     */
+    private _resolveRawBars;
+    /**
+     * 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.
      */
-    computeAt(market: MarketProvider, date: string): Promise<number | null>;
+    private _resolveRawBarAt;
+    /**
+     * 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.
+     */
+    private _readStoredBars;
     series(range?: DateRange): Promise<DailyBar[]>;
     private _syntheticThresholdSeries;
     value(date?: string): Promise<number | null>;
     /**
-     * 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.
      */
-    previewSeries(date: string, quoteOverrides: Record<string, number>, range?: DateRange): Promise<DailyBar[]>;
+    previewSeries(date: string, overrides: Record<string, number>, range?: DateRange): Promise<DailyBar[]>;
 }
 
 interface StorageProvider {
@@ -194,9 +229,16 @@ interface StorageProvider {
             id: number;
         }>;
         getSeries(indicatorId: number, range?: DateRange): Promise<DailyBar[]>;
-        writeSeries(indicatorId: number, bars: DailyBar[]): Promise<void>;
+        writeSeries(indicatorId: number, bars: DailyBar[], opts?: {
+            metadata?: unknown;
+        }): Promise<void>;
         getLatestSeriesDate(indicatorId: number): Promise<string | null>;
         getValue(indicatorId: number, date?: string): Promise<number | null>;
+        getLatestBar(indicatorId: number): Promise<{
+            date: string;
+            value: number;
+            metadata: unknown;
+        } | null>;
     };
     signals: {
         upsert(identity: {
@@ -253,13 +295,12 @@ declare class SignalHandle {
     readonly comparison: Comparison;
     readonly tolerance: number;
     private _storage;
-    private _market;
     private _resolvedId;
     private _resolving;
     private _cachedSeries;
     private _cachedAsOf;
     private _syncing;
-    constructor(storage: StorageProvider, market: MarketProvider, identity: SignalIdentity);
+    constructor(storage: StorageProvider, _market: MarketProvider, identity: SignalIdentity);
     get id(): number;
     resolve(): Promise<{
         id: number;
@@ -270,14 +311,16 @@ declare class SignalHandle {
     private _getLatestSignalSeriesDate;
     private _getLastSignalValue;
     private _ensureFresh;
+    private _isSingleBarFastPath;
     private _sync;
+    private _evaluateOneBar;
     private _upsertSeries;
     private _querySeriesFromDb;
-    withMarket(market: MarketProvider): SignalHandle;
     /**
-     * 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
@@ -285,19 +328,19 @@ declare class SignalHandle {
      *   standalone callers). On the preview path `_evaluate` passes this from
      *   the in-memory `dateMap` so we never read stale storage.
      */
-    computeAt(market: MarketProvider, date: string, prevBool?: boolean | null): Promise<boolean | null>;
+    computeAt(date: string, overrides?: Record<string, number>, prevBool?: boolean | null): Promise<boolean | null>;
     series(range?: DateRange): Promise<DailyBar[]>;
     value(date?: string): Promise<number | null>;
     /**
      * 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.
      */
-    previewSeries(date: string, quoteOverrides: Record<string, number>, range?: DateRange): Promise<DailyBar[]>;
+    previewSeries(date: string, overrides: Record<string, number>, range?: DateRange): Promise<DailyBar[]>;
 }
 
 declare class AllocationHandle {
@@ -311,6 +354,11 @@ declare class AllocationHandle {
         id: number;
     }>;
     static fromResolved(storage: StorageProvider, id: number, holdings: [TickerHandle, number][]): AllocationHandle;
+    toJSON(): Array<{
+        symbol: string;
+        leverage: number;
+        weight: number;
+    }>;
     private _doResolve;
 }
 
@@ -348,6 +396,45 @@ interface FinalState {
     closePrices: Record<string, number>;
     leveragedPrices: Record<string, number>;
 }
+/** Per-signal slice of a live strategy snapshot. */
+interface LiveSignalState {
+    indicator1: {
+        value: number | null;
+        date: string | null;
+    };
+    indicator2: {
+        value: number | null;
+        date: string | null;
+    };
+    isTrue: boolean;
+}
+/** Per-rule collection of live signal states, in the same order as the rule's `when` list. */
+interface LiveRuleState {
+    signals: LiveSignalState[];
+}
+/** Full live strategy view for a single evaluation date — no portfolio info. */
+interface StrategyLiveState {
+    allocation: AllocationHandle | null;
+    activeRuleIndex: number;
+    rules: LiveRuleState[];
+}
+/**
+ * Combined live state returned by `SimulationHandle.pushAndPreview`: both the
+ * portfolio snapshot from a `push` and the strategy evaluation at the target
+ * date under the accumulated live-quote overrides.
+ */
+interface LivePreviewState extends StrategyLiveState {
+    snapshot: PortfolioSnapshot;
+}
+/**
+ * Callback shape that `SimulationHandle.pushAndPreview` delegates to. Exists
+ * purely to break the circular import between `SimulationHandle` (in this
+ * file) and `StrategyHandle` (which creates simulations) — a strategy passes
+ * a bound `(date, overrides) => previewLiveState(...)` into the handle.
+ */
+interface LiveEvaluator {
+    previewLiveState(date: string, overrides: Record<string, number>): Promise<StrategyLiveState>;
+}
 declare class SimulationHandle {
     readonly series: DailyBar[];
     readonly trades: Trade[];
@@ -358,8 +445,30 @@ declare class SimulationHandle {
     private _lastLeveragedPrices;
     private _currentLeveragedPrices;
     private _lastDate;
-    constructor(series: DailyBar[], trades: Trade[], startingPortfolio: PortfolioHandle, finalState?: FinalState);
+    private _pushedQuotes;
+    private _liveEvaluator;
+    constructor(series: DailyBar[], trades: Trade[], startingPortfolio: PortfolioHandle, finalState?: FinalState, liveEvaluator?: LiveEvaluator);
     push(...prices: [TickerHandle, number][]): PortfolioSnapshot;
+    /**
+     * 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.
+     */
+    pushAndPreview(quotes: Record<string, number>, options?: {
+        date?: string;
+    }): Promise<LivePreviewState>;
 }
 
 interface StrategyRule {
@@ -398,6 +507,7 @@ declare class StrategyHandle {
     get freq(): TradingFreq;
     get offset(): number;
     get rules(): StrategyRule[];
+    marketSymbols(): string[];
     resolve(): Promise<{
         id: number;
     }>;
@@ -410,16 +520,22 @@ declare class StrategyHandle {
     /**
      * 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.
      */
     private _evaluate;
+    private _evaluateCold;
     private _querySeriesFromDb;
     series(range?: DateRange): Promise<StrategyBar[]>;
     value(date?: string): Promise<AllocationHandle | null>;
@@ -430,23 +546,34 @@ declare class StrategyHandle {
      * 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.
      */
-    previewAllocation(date: string, quoteOverrides: Record<string, number>): Promise<AllocationHandle | null>;
+    previewAllocation(date: string, overrides: Record<string, number>): Promise<AllocationHandle | 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`.
+     * 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.
      */
-    previewSeries(date: string, quoteOverrides: Record<string, number>, range?: DateRange): Promise<StrategyBar[]>;
+    previewSeries(date: string, overrides: Record<string, number>, range?: DateRange): Promise<StrategyBar[]>;
+    /**
+     * 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.
+     */
+    previewLiveState(date: string, overrides: Record<string, number>): Promise<StrategyLiveState>;
     private _fetchPricesForTickers;
     private _fetchRawClosePrices;
 }
@@ -498,4 +625,8 @@ interface PriceStream {
     close(): void;
 }
 
-export { AllocationHandle, type Comparison, type DailyBar, type DateRange, IndicatorHandle, type IndicatorIdentity, type IndicatorType, type LivefolioClient, type LivefolioClientOptions, type MarketProvider, PortfolioHandle, type PortfolioSnapshot, type PriceStream, SignalHandle, type SignalIdentity, type SimulateOptions, SimulationHandle, type StorageProvider, type StrategyBar, type StrategyDefinition, StrategyHandle, type StrategyOptions, type StrategyReferenceData, type StrategyRule, type StrategyRuleDefinition, type StrategySeriesEntry, type StreamStatus, TickerHandle, type Trade, type TradingFreq, type Unit, createClient };
+declare function allocationsEqual(a: AllocationHandle | null, b: AllocationHandle | null): boolean;
+
+declare function computeRebalanceDates(tradingDays: string[], freq: TradingFreq, offset: number): Set<string>;
+
+export { AllocationHandle, type Comparison, type DailyBar, type DateRange, IndicatorHandle, type IndicatorIdentity, type IndicatorType, type LiveEvaluator, type LivePreviewState, type LiveRuleState, type LiveSignalState, type LivefolioClient, type LivefolioClientOptions, type MarketProvider, PortfolioHandle, type PortfolioSnapshot, type PriceStream, SignalHandle, type SignalIdentity, type SimulateOptions, SimulationHandle, type StorageProvider, type StrategyBar, type StrategyDefinition, StrategyHandle, type StrategyLiveState, type StrategyOptions, type StrategyReferenceData, type StrategyRule, type StrategyRuleDefinition, type StrategySeriesEntry, type StreamStatus, TickerHandle, type Trade, type TradingFreq, type Unit, allocationsEqual, computeRebalanceDates, createClient };