@livefolio/sdk 0.5.0-rc.2 → 0.5.0-rc.3

package/dist/index.d.ts

@@ -1599,6 +1599,27 @@ declare class FeatureRuntime {
     compute(spec: FeatureSpec, asset: Asset): Promise<Series>;
 }
 
+/**
+ * A scheduled cash injection or withdrawal. Applied at the start of the
+ * matching session — BEFORE `universe`/`features`/`build` — by `runBacktest`
+ * (see Task 10 wiring). Events with `t <= sessionT` that have not yet been
+ * consumed are applied (and summed) on that session.
+ */
+type CashEvent = {
+    t: Date;
+    /** Positive = deposit, negative = withdrawal. */
+    delta: number;
+    /**
+     * Optional attribution tag for downstream metrics. `'deposit'`/`'withdrawal'`
+     * are the natural tags for user-scheduled flows (this surface's main use case).
+     * `'interest'`/`'dividend'` are accepted for callers who want to tag a
+     * manually-scheduled flow as income, but the SDK's automatic per-session
+     * interest/dividend hooks do NOT emit `CashEvent`s — they credit cash directly
+     * and report via `BacktestSnapshot.interestIncome`/`dividendIncome`. User code
+     * typically only sets `'deposit'`/`'withdrawal'`.
+     */
+    reason?: 'deposit' | 'withdrawal' | 'interest' | 'dividend';
+};
 /**
  * All inputs required to run a historical backtest.
  *
@@ -1653,6 +1674,16 @@ type RunBacktestOptions<F extends Features = Features, S = unknown> = {
      * runtime seed its buffer from the historical bars without refetching).
      */
     featureRuntime?: FeatureRuntime;
+    /**
+     * Optional scheduled deposits/withdrawals applied per-session before the
+     * strategy runs. Matched by `t <= sessionT`; multiple due events are summed.
+     * Defaults to none (today's behavior). See `BacktestSnapshot.cashFlow`.
+     *
+     * @remarks A withdrawal that exceeds available cash is allowed to drive cash
+     * negative (logged via `console.warn`); automatic force-selling of holdings to
+     * fund withdrawals is deferred to a later release, so this behavior may change.
+     */
+    cashEvents?: ReadonlyArray<CashEvent>;
 };
 /**
  * A point-in-time snapshot of the simulation at the end of a single trading session.
@@ -1669,6 +1700,10 @@ type BacktestSnapshot = {
     orders: ReadonlyArray<Order>;
     /** Fills returned by the executor for the orders above. */
     fills: ReadonlyArray<Fill>;
+    /**
+     * Net cash delta applied this session via `cashEvents`. Omitted when zero.
+     */
+    cashFlow?: number;
 };
 /**
  * The return value of `runBacktest`, containing the full simulation history
@@ -1820,6 +1855,18 @@ interface StreamingDataFeed {
     subscribe(assets: ReadonlyArray<Asset>): AsyncIterable<StreamingBar>;
 }
 
+/**
+ * Mutable queue for scheduling {@link CashEvent}s into a running `runLive`
+ * stream. Construct one, pass it via {@link RunLiveOptions.cashEventQueue}, and
+ * `push` events from outside the generator; they are drained at each session
+ * close. A non-breaking alternative to a returned scheduling handle.
+ */
+declare class CashEventQueue {
+    private pending;
+    push(e: CashEvent): void;
+    /** Remove and return events with `t <= now`, leaving later events queued. */
+    drainDue(now: Date): CashEvent[];
+}
 /**
  * Unified event stream from {@link runLive}. Discriminated union of two variants:
  *
@@ -1861,6 +1908,25 @@ type LiveEvent<F extends Features = Features, _S = unknown> = {
      * `portfolio` + `prices`.
      */
     previewPortfolio: Portfolio;
+} | {
+    /**
+     * A net cash injection/withdrawal applied to the committed portfolio at a
+     * session close. Emitted BEFORE the `snapshot` for that session, so the
+     * subsequent snapshot's `portfolio.cash` already reflects this delta.
+     * Only emitted when the summed delta of due events is non-zero.
+     */
+    type: 'cash';
+    /** Session-close timestamp at which the delta was applied. */
+    t: Date;
+    /** Net cash delta applied (sum of all due events). Positive = deposit. */
+    delta: number;
+    /**
+     * Attribution tag of the FIRST contributing event. When multiple cash
+     * events are due at the same session close they are summed into one delta
+     * and the other reasons are dropped — use `cashEventQueue` and drain
+     * manually if you need per-event attribution.
+     */
+    reason?: CashEvent['reason'];
 } | (BacktestSnapshot & {
     type: 'snapshot';
 });
@@ -1891,6 +1957,20 @@ type RunLiveOptions<F extends Features = Features, S = unknown> = {
      * seeded from `history.bars`.
      */
     streamingRuntime?: FeatureRuntime;
+    /**
+     * Cash injections/withdrawals known up front. Each is applied to the
+     * committed portfolio at the first session close whose date is `>= e.t`,
+     * summed with any other due events for that session. For dynamic scheduling
+     * after the stream has started, use {@link RunLiveOptions.cashEventQueue}.
+     */
+    cashEvents?: ReadonlyArray<CashEvent>;
+    /**
+     * Optional mutable queue for scheduling cash events into the running stream
+     * from outside the generator. Drained (alongside `cashEvents`) at each
+     * session close. Construct a {@link CashEventQueue}, pass it here, and `push`
+     * events as they arrive.
+     */
+    cashEventQueue?: CashEventQueue;
 };
 /**
  * Drives a {@link Strategy} against a streaming market-data source and yields
@@ -3977,4 +4057,4 @@ declare function applyOrders(portfolio: Portfolio, orders: ReadonlyArray<Order>)
  */
 declare function positionsByAsset(portfolio: Portfolio): Position[];
 
-export { type AdhocTimeOverrides, type AdjustOrder, type AllocateNode, type Asset, type AssetId, type AssetRef, BacktestExecutor, type BacktestExecutorOptions, type BacktestResult, type BacktestSnapshot, type Bar, type BarField, type Calendar, type CloseOrder, type Comparison, type ComparisonOp, type ComputeFn, Crypto24x7Calendar, type DataEvent, type DataFeed, type DateRange, type EquityAsset, type EventKind, ExchangeCalendar, type ExchangeName, type Executor, type FeatureCache, type FeatureKey, type FeatureKind, type FeatureRef, FeatureRuntime, type FeatureRuntimeOptions, type FeatureScope, type FeatureSpec, type Features, type Fill, type Frequency, type FromSpecOptions, type Fundamentals, type HolidayRule, type IfNode, type IncomeKind, LSEExchangeCalendar, type LiveEvent, type Lot, type LotSlice, type MacroAsset, MemoryFeatureCache, NYSEExchangeCalendar, type NextOpenFn, ORDINARY_OFFSET_CAP, type OpenOrder, type Order, type PollingSchedule, type PollingStreamOptions, type Portfolio, type Position, type PositionId, type PriceMap, type Quote, type QuoteFeed, type RealizeResult, type RealizedEvent, type RebalanceConfig, type RebalanceFrequency, type RebalanceOrder, type ReturnMode, RoutingDataFeed, RoutingDataFeedError, type RoutingDataFeedRouteFn, type RoutingDataFeedRouteMap, RoutingQuoteFeed, RoutingQuoteFeedError, type RoutingQuoteFeedRouteFn, type RoutingQuoteFeedRouteMap, RoutingStreamingDataFeed, RoutingStreamingDataFeedError, type RoutingStreamingDataFeedRouteFn, type RoutingStreamingDataFeedRouteMap, type RuleNode, type RuleTreeState, type RunBacktestOptions, type RunLiveOptions, type Series, type Session, type SpecialClose, type SpecialOpen, type Strategy, type StreamingBar, type StreamingDataFeed, type SyntheticAsset, type TacticalFeatureKind, type TacticalFeatureSpec, type TacticalFeatures, type TacticalSpec, type TargetWeights, type TaxRates, type TaxableIncome, type TimeOfDay, type Tolerance, type WithStreamingSyntheticsOptions, aggregateByYear, applyFills, applyOrders, barsToSeries, bucketByTerm, collectBars, computeTaxBill, crossOffset, defineFeature, drawdown, ema, evaluateFeatureSpecs, evaluateRuleTree, index$1 as features, fromSpec, getCalendar, getFeatureCompute, holdingPeriodDays, isLongTerm, isRebalanceDay, netWithinBucket, paramsHash, periodKey, pollingStreamFromHistorical, positionsByAsset, realize, reconcile, returnSeries, rsi, runBacktest, runLive, selectFIFO, selectHIFO, selectLIFO, selectMinTax, seriesAt, sma, index$2 as tactical, index as tax, volatility, withStreamingSynthetics, withSynthetics };
+export { type AdhocTimeOverrides, type AdjustOrder, type AllocateNode, type Asset, type AssetId, type AssetRef, BacktestExecutor, type BacktestExecutorOptions, type BacktestResult, type BacktestSnapshot, type Bar, type BarField, type Calendar, type CashEvent, CashEventQueue, type CloseOrder, type Comparison, type ComparisonOp, type ComputeFn, Crypto24x7Calendar, type DataEvent, type DataFeed, type DateRange, type EquityAsset, type EventKind, ExchangeCalendar, type ExchangeName, type Executor, type FeatureCache, type FeatureKey, type FeatureKind, type FeatureRef, FeatureRuntime, type FeatureRuntimeOptions, type FeatureScope, type FeatureSpec, type Features, type Fill, type Frequency, type FromSpecOptions, type Fundamentals, type HolidayRule, type IfNode, type IncomeKind, LSEExchangeCalendar, type LiveEvent, type Lot, type LotSlice, type MacroAsset, MemoryFeatureCache, NYSEExchangeCalendar, type NextOpenFn, ORDINARY_OFFSET_CAP, type OpenOrder, type Order, type PollingSchedule, type PollingStreamOptions, type Portfolio, type Position, type PositionId, type PriceMap, type Quote, type QuoteFeed, type RealizeResult, type RealizedEvent, type RebalanceConfig, type RebalanceFrequency, type RebalanceOrder, type ReturnMode, RoutingDataFeed, RoutingDataFeedError, type RoutingDataFeedRouteFn, type RoutingDataFeedRouteMap, RoutingQuoteFeed, RoutingQuoteFeedError, type RoutingQuoteFeedRouteFn, type RoutingQuoteFeedRouteMap, RoutingStreamingDataFeed, RoutingStreamingDataFeedError, type RoutingStreamingDataFeedRouteFn, type RoutingStreamingDataFeedRouteMap, type RuleNode, type RuleTreeState, type RunBacktestOptions, type RunLiveOptions, type Series, type Session, type SpecialClose, type SpecialOpen, type Strategy, type StreamingBar, type StreamingDataFeed, type SyntheticAsset, type TacticalFeatureKind, type TacticalFeatureSpec, type TacticalFeatures, type TacticalSpec, type TargetWeights, type TaxRates, type TaxableIncome, type TimeOfDay, type Tolerance, type WithStreamingSyntheticsOptions, aggregateByYear, applyFills, applyOrders, barsToSeries, bucketByTerm, collectBars, computeTaxBill, crossOffset, defineFeature, drawdown, ema, evaluateFeatureSpecs, evaluateRuleTree, index$1 as features, fromSpec, getCalendar, getFeatureCompute, holdingPeriodDays, isLongTerm, isRebalanceDay, netWithinBucket, paramsHash, periodKey, pollingStreamFromHistorical, positionsByAsset, realize, reconcile, returnSeries, rsi, runBacktest, runLive, selectFIFO, selectHIFO, selectLIFO, selectMinTax, seriesAt, sma, index$2 as tactical, index as tax, volatility, withStreamingSynthetics, withSynthetics };

package/dist/index.js

@@ -331,7 +331,24 @@ async function runBacktest(opts) {
   let portfolio = opts.initialPortfolio;
   let state = initialStateValue;
   const snapshots = [];
+  const cashEvents = [...opts.cashEvents ?? []].sort((a, b) => a.t.getTime() - b.t.getTime());
+  let eventCursor = 0;
+  let warnedNegativeCash = false;
   for (const t of sessions) {
+    let cashFlow = 0;
+    while (eventCursor < cashEvents.length && cashEvents[eventCursor].t.getTime() <= t.getTime()) {
+      cashFlow += cashEvents[eventCursor].delta;
+      eventCursor++;
+    }
+    if (cashFlow !== 0) {
+      portfolio = { ...portfolio, cash: portfolio.cash + cashFlow };
+      if (portfolio.cash < 0 && !warnedNegativeCash) {
+        warnedNegativeCash = true;
+        console.warn(
+          `[runBacktest] cash went negative at ${t.toISOString()}: ${portfolio.cash}. Withdrawals exceed available cash (force-sell is deferred); further occurrences this run are suppressed.`
+        );
+      }
+    }
     const universe = opts.strategy.universe(t, portfolio);
     const features = await opts.strategy.features(universe, portfolio, t);
     const buildResult = opts.strategy.build(features, portfolio, state, t);
@@ -344,7 +361,7 @@ async function runBacktest(opts) {
     }
     const fills = await opts.executor.submit(orders, t, portfolio);
     portfolio = applyFills(portfolio, fills, orders);
-    snapshots.push({ t, portfolio, orders, fills });
+    snapshots.push({ t, portfolio, orders, fills, ...cashFlow !== 0 ? { cashFlow } : {} });
   }
   const bars = opts.featureRuntime?.getAllBars() ?? /* @__PURE__ */ new Map();
   return { snapshots, finalPortfolio: portfolio, finalState: state, bars };
@@ -757,6 +774,18 @@ var MemoryFeatureCache = class {
 };
 
 // src/strategy/run-live.ts
+var CashEventQueue = class {
+  pending = [];
+  push(e) {
+    this.pending.push(e);
+  }
+  /** Remove and return events with `t <= now`, leaving later events queued. */
+  drainDue(now) {
+    const due = this.pending.filter((e) => e.t.getTime() <= now.getTime());
+    if (due.length > 0) this.pending = this.pending.filter((e) => e.t.getTime() > now.getTime());
+    return due;
+  }
+};
 function snapshotState(state) {
   if (state === void 0) return void 0;
   return structuredClone(state);
@@ -775,6 +804,8 @@ async function* runLive(opts) {
   });
   let portfolio = history.finalPortfolio;
   let state = history.finalState;
+  const seedQueue = new CashEventQueue();
+  for (const e of opts.cashEvents ?? []) seedQueue.push(e);
   const anchorTime = history.snapshots.length > 0 ? history.snapshots[history.snapshots.length - 1].t : /* @__PURE__ */ new Date(0);
   const universe = strategy.universe(anchorTime, portfolio);
   let currentSession = history.snapshots.length > 0 ? calendar.next(history.snapshots[history.snapshots.length - 1].t) : null;
@@ -826,6 +857,17 @@ async function* runLive(opts) {
       }
       const fills = await executor.submit(orders, currentSession, portfolio);
       portfolio = applyFills(portfolio, fills, orders);
+      const dueCash = [...seedQueue.drainDue(currentSession), ...opts.cashEventQueue?.drainDue(currentSession) ?? []];
+      const cashDelta = dueCash.reduce((s, e) => s + e.delta, 0);
+      if (cashDelta !== 0) {
+        portfolio = { ...portfolio, cash: portfolio.cash + cashDelta };
+        yield {
+          type: "cash",
+          t: currentSession,
+          delta: cashDelta,
+          reason: dueCash[0]?.reason
+        };
+      }
       yield {
         type: "snapshot",
         t: currentSession,
@@ -3258,6 +3300,7 @@ function positionsByAsset(portfolio) {
 }
 export {
   BacktestExecutor,
+  CashEventQueue,
   Crypto24x7Calendar,
   ExchangeCalendar,
   FeatureRuntime,