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

package/dist/index.d.ts

@@ -127,6 +127,22 @@ type Series = ReadonlyArray<{
     t: Date;
     v: number;
 }>;
+/**
+ * A cash distribution (dividend) or interest payment for an asset, carrying
+ * what the SDK needs to credit cash and classify the income per-lot.
+ *
+ * `incomeKind: 'qualified-eligible'` means the distribution CAN be qualified if
+ * a holding lot satisfies the 60-of-121-day rule; the runtime resolves the
+ * actual qualified-vs-ordinary split per lot. `'ordinary'`/`'interest'` are
+ * never qualified.
+ */
+type DividendEvent = {
+    asset: Asset;
+    exDate: Date;
+    payDate: Date;
+    amountPerShare: number;
+    incomeKind: 'qualified-eligible' | 'ordinary' | 'interest';
+};
 
 /**
  * Stable opaque string identifier for a {@link Position}. Generated by the
@@ -187,7 +203,7 @@ type IncomeKind = 'capital-gain' | 'qualified-dividend' | 'ordinary-dividend' |
  * sales reduce `quantity` and pro-rate `basis`.
  */
 type Lot = {
-    /** Opaque id assigned by {@link nextLotId} on creation. */
+    /** Opaque id assigned by `nextLotId` (internal) on creation. */
     id: string;
     asset: Asset;
     /** Shares remaining in this lot after any partial sales. */
@@ -767,9 +783,13 @@ interface DataFeed {
      * @param asset - The instrument to fetch bars for.
      * @param range - Half-open date range; `range.from` inclusive, `range.to` exclusive.
      * @param freq  - Bar width. `'1d'` returns one bar per trading day.
+     * @param kind  - `'adjusted'` (default) applies split/dividend adjustments;
+     *   `'unadjusted'` returns raw prices. Indicators consume adjusted bars;
+     *   execution fills and dividend cash-flow use unadjusted bars. Vendors that
+     *   do not distinguish may ignore this and always return their single series.
      * @returns An async iterable of {@link Bar} objects.
      */
-    bars(asset: Asset, range: DateRange, freq: Frequency): AsyncIterable<Bar>;
+    bars(asset: Asset, range: DateRange, freq: Frequency, kind?: 'adjusted' | 'unadjusted'): AsyncIterable<Bar>;
     /**
      * Returns a snapshot of fundamental data for `asset` as of `t`.
      * Optional — not all data providers carry fundamentals.
@@ -790,6 +810,17 @@ interface DataFeed {
      * @returns An async iterable of {@link DataEvent} objects.
      */
     events?(range: DateRange, kinds: ReadonlyArray<EventKind>): AsyncIterable<DataEvent>;
+    /**
+     * Returns cash distributions (dividends / interest) for `asset` over `range`.
+     * Optional — providers without dividend data omit it. Consumed by
+     * `runBacktest`'s per-session dividend hook. Amounts are per-share, on the
+     * unadjusted price basis.
+     *
+     * @param asset - The instrument to query.
+     * @param range - Half-open date range.
+     * @returns A promise resolving to an array of {@link DividendEvent} objects.
+     */
+    dividends?(asset: Asset, range: DateRange): Promise<DividendEvent[]>;
 }
 
 /**
@@ -1599,6 +1630,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 +1705,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 +1731,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 +1886,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 +1939,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 +1988,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
@@ -2122,6 +2233,28 @@ type BacktestExecutorOptions = {
      * the fill quantity and recorded in `Fill.fees`. Defaults to `0`.
      */
     perShareFee?: number;
+    /**
+     * Tax-lot selection method applied to long sells (a `rebalance` reduce or a
+     * `close` of a long position). When set to a non-default method
+     * (`'LIFO'` / `'HIFO'` / `'min-tax'`), such a sell is split into one
+     * {@link Fill} per selected lot — each carrying `Fill.lotId` — so
+     * {@link applyFills} consumes those exact lots.
+     *
+     * Defaults to `'FIFO'` (equivalently, leaving this unset): the executor emits
+     * a single fill per order with no `lotId`, and `applyFills` performs its own
+     * internal FIFO. Buys, short-side closes, and `adjust` orders are never split.
+     */
+    lotMethod?: 'FIFO' | 'LIFO' | 'HIFO' | 'min-tax';
+    /**
+     * Short- and long-term capital-gains tax rates (as decimals, e.g. `0.37`)
+     * forwarded to the `'min-tax'` selector. **Required** when
+     * `lotMethod === 'min-tax'`; the constructor throws otherwise. Ignored for
+     * all other lot methods.
+     */
+    taxRates?: {
+        shortTerm: number;
+        longTerm: number;
+    };
 };
 /**
  * Reference {@link Executor} implementation for backtesting. Fills each order
@@ -2142,6 +2275,12 @@ type BacktestExecutorOptions = {
  * A flat per-share fee is added to `Fill.fees`. Orders with zero quantity are
  * silently skipped.
  *
+ * **Lot selection**: by default each order yields exactly one fill. When a
+ * non-default `lotMethod` (`'LIFO'` / `'HIFO'` / `'min-tax'`) is configured,
+ * long sells (a `rebalance` reduce or a `close` of a long position) are split
+ * into one fill per selected lot — each tagged with `Fill.lotId` — so
+ * {@link applyFills} consumes those exact lots. See {@link BacktestExecutorOptions.lotMethod}.
+ *
  * @example
  * ```ts
  * import { BacktestExecutor } from '@livefolio/sdk';
@@ -2170,7 +2309,8 @@ declare class BacktestExecutor implements Executor {
  * when the routed feed does not support the requested optional method.
  *
  * Distinguish the two cases via the message text: "no feed registered" vs
- * "does not implement fundamentals".
+ * "does not implement `<method>`" (e.g. "does not implement fundamentals()" or
+ * "does not implement dividends()").
  */
 declare class RoutingDataFeedError extends Error {
     constructor(message: string);
@@ -2191,9 +2331,11 @@ type RoutingDataFeedRouteMap = Readonly<Partial<Record<Asset['kind'], DataFeed>>
  * - **Function form:** `new RoutingDataFeed((a) => a.kind === 'macro' ? fred : yahoo)`.
  *   Use when routing depends on more than `kind` (e.g. allowlists).
  *
- * The router does **not** implement `events()` — the optional method is
- * genuinely absent (`'events' in router === false`). Cross-feed event
- * fan-out is deferred until a real consumer materializes.
+ * `dividends()` and `fundamentals()` ARE implemented — each targets a single
+ * asset, so it resolves to that asset's routed feed (or throws if the feed
+ * lacks the method). The router does **not** implement `events()` — the
+ * optional method is genuinely absent (`'events' in router === false`) because
+ * cross-feed event fan-out is a separate, deferred problem.
  *
  * @example
  * ```ts
@@ -2212,8 +2354,17 @@ type RoutingDataFeedRouteMap = Readonly<Partial<Record<Asset['kind'], DataFeed>>
 declare class RoutingDataFeed implements DataFeed {
     private readonly route;
     constructor(routes: RoutingDataFeedRouteMap | RoutingDataFeedRouteFn);
-    bars(asset: Asset, range: DateRange, freq: Frequency): AsyncGenerator<Bar>;
+    bars(asset: Asset, range: DateRange, freq: Frequency, kind?: 'adjusted' | 'unadjusted'): AsyncGenerator<Bar>;
     fundamentals(asset: Asset, t: Date): Promise<Fundamentals>;
+    /**
+     * Resolves `asset` to its routed feed and delegates `dividends`. This method
+     * is ALWAYS present on the router (unlike a leaf feed's optional `dividends?`),
+     * so `typeof routingFeed.dividends === 'function'` is always `true` — capability
+     * detection must account for the routed feed possibly lacking it at call time.
+     *
+     * @throws {RoutingDataFeedError} when the routed feed does not implement `dividends`.
+     */
+    dividends(asset: Asset, range: DateRange): Promise<DividendEvent[]>;
     private resolve;
 }
 
@@ -3114,7 +3265,7 @@ declare function evaluateFeatureSpecs(specs: ReadonlyArray<TacticalFeatureSpec>,
  * independently scaled); `volume` is passed through from the underlying bar.
  *
  * Non-synthetic assets are proxied transparently to the original `dataFeed`.
- * `fundamentals` and `events` methods, if present, are forwarded unchanged.
+ * `fundamentals`, `events`, and `dividends` methods, if present, are forwarded unchanged.
  *
  * Throws at construction time if `synthetics` contains duplicate `id` values.
  *
@@ -3977,4 +4128,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 DividendEvent, 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,
@@ -867,40 +909,124 @@ async function* runLive(opts) {
   }
 }
 
+// src/tax/lot-selection.ts
+function take(sorted, qty) {
+  let need = qty;
+  const out = [];
+  for (const lot of sorted) {
+    if (lot.quantity <= 0) continue;
+    if (need <= 0) break;
+    const q = Math.min(lot.quantity, need);
+    out.push({ lotId: lot.id, quantity: q });
+    need -= q;
+  }
+  if (need > 1e-9) {
+    const held = sorted.reduce((s, l) => s + Math.max(0, l.quantity), 0);
+    throw new RangeError(`lot-selection: need ${qty} but only ${held} held`);
+  }
+  return out;
+}
+function selectFIFO(lots, qty) {
+  return take(
+    [...lots].sort((a, b) => a.openDate.getTime() - b.openDate.getTime()),
+    qty
+  );
+}
+function selectLIFO(lots, qty) {
+  return take(
+    [...lots].sort((a, b) => b.openDate.getTime() - a.openDate.getTime()),
+    qty
+  );
+}
+function selectHIFO(lots, qty) {
+  return take(
+    [...lots].filter((l) => l.quantity > 0).sort((a, b) => b.basis / b.quantity - a.basis / a.quantity),
+    qty
+  );
+}
+function selectMinTax(lots, qty, ctx) {
+  const tier = (l) => {
+    const gainPerShare = ctx.price - l.basis / l.quantity;
+    const lt = isLongTerm(holdingPeriodDays(l, ctx.asOf));
+    if (gainPerShare < 0) return lt ? 0 : 1;
+    return lt ? 2 : 3;
+  };
+  const sorted = [...lots].filter((l) => l.quantity > 0).sort((a, b) => {
+    const ta = tier(a);
+    const tb = tier(b);
+    if (ta !== tb) return ta - tb;
+    const gainA = ctx.price - a.basis / a.quantity;
+    const gainB = ctx.price - b.basis / b.quantity;
+    return gainA - gainB;
+  });
+  return take(sorted, qty);
+}
+
 // src/reference/backtest-executor.ts
 function resolveAsset(order, portfolio) {
   switch (order.kind) {
     case "open":
-      return { asset: order.asset, sign: order.side === "long" ? 1 : -1, qty: order.quantity };
+      return { asset: order.asset, sign: order.side === "long" ? 1 : -1, qty: order.quantity, lotConsumingSell: false };
     case "rebalance":
-      return { asset: order.asset, sign: order.delta >= 0 ? 1 : -1, qty: Math.abs(order.delta) };
+      return {
+        asset: order.asset,
+        sign: order.delta >= 0 ? 1 : -1,
+        qty: Math.abs(order.delta),
+        lotConsumingSell: order.delta < 0
+      };
     case "close": {
       const p = portfolio.positions.find((x) => x.id === order.positionId);
       if (!p) throw new Error(`BacktestExecutor: close target position ${order.positionId} not found`);
-      return { asset: p.asset, sign: p.side === "long" ? -1 : 1, qty: order.quantity ?? p.quantity };
+      return {
+        asset: p.asset,
+        sign: p.side === "long" ? -1 : 1,
+        qty: order.quantity ?? p.quantity,
+        lotConsumingSell: p.side === "long"
+      };
     }
     case "adjust": {
       const p = portfolio.positions.find((x) => x.id === order.positionId);
       if (!p) throw new Error(`BacktestExecutor: adjust target position ${order.positionId} not found`);
       const target = order.changes.quantity ?? p.quantity;
       const delta = target - p.quantity;
-      return { asset: p.asset, sign: delta >= 0 ? 1 : -1, qty: Math.abs(delta) };
+      return { asset: p.asset, sign: delta >= 0 ? 1 : -1, qty: Math.abs(delta), lotConsumingSell: false };
     }
   }
 }
 var BacktestExecutor = class {
   constructor(opts) {
     this.opts = opts;
+    if (opts.lotMethod === "min-tax" && !opts.taxRates) {
+      throw new Error("BacktestExecutor: lotMethod 'min-tax' requires taxRates");
+    }
   }
   async submit(orders, t, portfolio) {
     const fills = [];
     const slip = (this.opts.slippageBps ?? 0) / 1e4;
     const feePer = this.opts.perShareFee ?? 0;
+    const method = this.opts.lotMethod;
     for (const order of orders) {
-      const { asset, sign, qty } = resolveAsset(order, portfolio);
+      const { asset, sign, qty, lotConsumingSell } = resolveAsset(order, portfolio);
       if (qty === 0) continue;
       const open = await this.opts.nextOpen(asset, t);
       const adjustedPrice = open.price * (1 + sign * slip);
+      if (method && method !== "FIFO" && lotConsumingSell) {
+        const lots = (portfolio.lots ?? []).filter((l) => l.asset.id === asset.id && l.quantity > 0);
+        if (lots.length > 0) {
+          const slices = method === "LIFO" ? selectLIFO(lots, qty) : method === "HIFO" ? selectHIFO(lots, qty) : selectMinTax(lots, qty, { price: adjustedPrice, asOf: open.t, rates: this.opts.taxRates });
+          for (const slice of slices) {
+            fills.push({
+              orderRef: order.id,
+              t: open.t,
+              quantity: slice.quantity,
+              price: adjustedPrice,
+              fees: feePer * slice.quantity,
+              lotId: slice.lotId
+            });
+          }
+          continue;
+        }
+      }
       fills.push({
         orderRef: order.id,
         t: open.t,
@@ -932,9 +1058,9 @@ var RoutingDataFeed = class {
   // Async generator (rather than plain delegation) so resolve() runs lazily on
   // the first next() call, surfacing errors via the iterable's normal rejection
   // path instead of throwing synchronously at call time.
-  async *bars(asset, range, freq) {
+  async *bars(asset, range, freq, kind) {
     const feed = this.resolve(asset);
-    yield* feed.bars(asset, range, freq);
+    yield* feed.bars(asset, range, freq, kind);
   }
   async fundamentals(asset, t) {
     const feed = this.resolve(asset);
@@ -945,6 +1071,23 @@ var RoutingDataFeed = class {
     }
     return feed.fundamentals(asset, t);
   }
+  /**
+   * Resolves `asset` to its routed feed and delegates `dividends`. This method
+   * is ALWAYS present on the router (unlike a leaf feed's optional `dividends?`),
+   * so `typeof routingFeed.dividends === 'function'` is always `true` — capability
+   * detection must account for the routed feed possibly lacking it at call time.
+   *
+   * @throws {RoutingDataFeedError} when the routed feed does not implement `dividends`.
+   */
+  async dividends(asset, range) {
+    const feed = this.resolve(asset);
+    if (typeof feed.dividends !== "function") {
+      throw new RoutingDataFeedError(
+        `RoutingDataFeed: routed feed for asset.kind="${asset.kind}" (id="${asset.id}") does not implement dividends()`
+      );
+    }
+    return feed.dividends(asset, range);
+  }
   resolve(asset) {
     const feed = this.route(asset);
     if (feed === void 0) {
@@ -2838,11 +2981,13 @@ function withSynthetics(dataFeed, synthetics) {
     byId.set(s.id, s);
   }
   const wrapped = {
-    bars(asset, range, freq) {
+    // `kind` ('adjusted' | 'unadjusted') is forwarded to the underlying feed
+    // before synthesis so synthetic bars derive from the requested price series.
+    bars(asset, range, freq, kind) {
       const synth = byId.get(asset.id);
-      if (!synth) return dataFeed.bars(asset, range, freq);
+      if (!synth) return dataFeed.bars(asset, range, freq, kind);
       const underlying = resolveAssetRef(synth.underlying);
-      return synthesize(dataFeed.bars(underlying, range, freq), synth.leverage, synth.expense);
+      return synthesize(dataFeed.bars(underlying, range, freq, kind), synth.leverage, synth.expense);
     }
   };
   if (dataFeed.fundamentals) {
@@ -2851,6 +2996,9 @@ function withSynthetics(dataFeed, synthetics) {
   if (dataFeed.events) {
     wrapped.events = dataFeed.events.bind(dataFeed);
   }
+  if (dataFeed.dividends) {
+    wrapped.dividends = dataFeed.dividends.bind(dataFeed);
+  }
   return wrapped;
 }
 function withStreamingSynthetics(inner, synthetics, opts) {
@@ -3085,59 +3233,6 @@ __export(tax_exports, {
   selectMinTax: () => selectMinTax
 });
 
-// src/tax/lot-selection.ts
-function take(sorted, qty) {
-  let need = qty;
-  const out = [];
-  for (const lot of sorted) {
-    if (lot.quantity <= 0) continue;
-    if (need <= 0) break;
-    const q = Math.min(lot.quantity, need);
-    out.push({ lotId: lot.id, quantity: q });
-    need -= q;
-  }
-  if (need > 1e-9) {
-    const held = sorted.reduce((s, l) => s + Math.max(0, l.quantity), 0);
-    throw new RangeError(`lot-selection: need ${qty} but only ${held} held`);
-  }
-  return out;
-}
-function selectFIFO(lots, qty) {
-  return take(
-    [...lots].sort((a, b) => a.openDate.getTime() - b.openDate.getTime()),
-    qty
-  );
-}
-function selectLIFO(lots, qty) {
-  return take(
-    [...lots].sort((a, b) => b.openDate.getTime() - a.openDate.getTime()),
-    qty
-  );
-}
-function selectHIFO(lots, qty) {
-  return take(
-    [...lots].filter((l) => l.quantity > 0).sort((a, b) => b.basis / b.quantity - a.basis / a.quantity),
-    qty
-  );
-}
-function selectMinTax(lots, qty, ctx) {
-  const tier = (l) => {
-    const gainPerShare = ctx.price - l.basis / l.quantity;
-    const lt = isLongTerm(holdingPeriodDays(l, ctx.asOf));
-    if (gainPerShare < 0) return lt ? 0 : 1;
-    return lt ? 2 : 3;
-  };
-  const sorted = [...lots].filter((l) => l.quantity > 0).sort((a, b) => {
-    const ta = tier(a);
-    const tb = tier(b);
-    if (ta !== tb) return ta - tb;
-    const gainA = ctx.price - a.basis / a.quantity;
-    const gainB = ctx.price - b.basis / b.quantity;
-    return gainA - gainB;
-  });
-  return take(sorted, qty);
-}
-
 // src/tax/aggregation.ts
 var ORDINARY_OFFSET_CAP = 3e3;
 function bucketByTerm(events) {
@@ -3258,6 +3353,7 @@ function positionsByAsset(portfolio) {
 }
 export {
   BacktestExecutor,
+  CashEventQueue,
   Crypto24x7Calendar,
   ExchangeCalendar,
   FeatureRuntime,