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

package/dist/index.js

@@ -54,6 +54,36 @@ function nextLotId() {
   return `lot_${++_lotCounter}`;
 }
 
+// src/tax/holding-period.ts
+var MS_PER_DAY = 864e5;
+function holdingPeriodDays(lot, asOf) {
+  return (asOf.getTime() - lot.openDate.getTime()) / MS_PER_DAY;
+}
+function isLongTerm(days) {
+  return days > 365;
+}
+function realize(lot, qty, salePrice, asOf) {
+  if (qty <= 0) throw new RangeError(`realize: qty must be positive, got ${qty}`);
+  if (qty > lot.quantity) throw new RangeError(`realize: lot ${lot.id} has ${lot.quantity}, cannot sell ${qty}`);
+  const basisPerShare = lot.basis / lot.quantity;
+  const basis = basisPerShare * qty;
+  const proceeds = qty * salePrice;
+  const event = {
+    asset: lot.asset,
+    lotId: lot.id,
+    quantity: qty,
+    openDate: lot.openDate,
+    closeDate: asOf,
+    proceeds,
+    basis,
+    termType: isLongTerm(holdingPeriodDays(lot, asOf)) ? "long" : "short",
+    gain: proceeds - basis,
+    incomeKind: "capital-gain"
+  };
+  const remainingLot = qty === lot.quantity ? null : { ...lot, quantity: lot.quantity - qty, basis: lot.basis - basis };
+  return { event, remainingLot };
+}
+
 // src/portfolio/apply.ts
 var newPositionId = /* @__PURE__ */ (() => {
   let n = 0;
@@ -62,8 +92,6 @@ var newPositionId = /* @__PURE__ */ (() => {
 function findOrder(orders, id) {
   return orders.find((o) => o.id === id);
 }
-var MS_PER_DAY = 864e5;
-var isLong = (openDate, closeDate) => (closeDate.getTime() - openDate.getTime()) / MS_PER_DAY > 365;
 function consumeLots(lots, realized, assetId, qty, price, fees, closeDate, preferLotId) {
   const sortedLots = lots.filter((l) => l.asset.id === assetId && l.quantity > 0).sort((a, b) => {
     if (preferLotId) {
@@ -80,25 +108,25 @@ function consumeLots(lots, realized, assetId, qty, price, fees, closeDate, prefe
   const totalQty = qty;
   for (const l of sortedLots) {
     if (need <= 0) break;
-    const take = Math.min(l.quantity, need);
+    const take2 = Math.min(l.quantity, need);
     const basisPerShare = l.basis / l.quantity;
-    const consumedBasis = basisPerShare * take;
-    const proceeds = take * price - take / totalQty * fees;
+    const consumedBasis = basisPerShare * take2;
+    const proceeds = take2 * price - take2 / totalQty * fees;
     realized.push({
       asset: l.asset,
       lotId: l.id,
-      quantity: take,
+      quantity: take2,
       openDate: l.openDate,
       closeDate,
       proceeds,
       basis: consumedBasis,
-      termType: isLong(l.openDate, closeDate) ? "long" : "short",
+      termType: isLongTerm(holdingPeriodDays(l, closeDate)) ? "long" : "short",
       gain: proceeds - consumedBasis,
       incomeKind: "capital-gain"
     });
-    l.quantity -= take;
+    l.quantity -= take2;
     l.basis -= consumedBasis;
-    need -= take;
+    need -= take2;
   }
 }
 function applyFills(portfolio, fills, orders) {
@@ -303,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);
@@ -316,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 };
@@ -729,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);
@@ -747,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;
@@ -798,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,
@@ -3039,6 +3109,164 @@ __export(features_exports, {
   volatility: () => volatility
 });
 
+// src/tax/index.ts
+var tax_exports = {};
+__export(tax_exports, {
+  ORDINARY_OFFSET_CAP: () => ORDINARY_OFFSET_CAP,
+  aggregateByYear: () => aggregateByYear,
+  bucketByTerm: () => bucketByTerm,
+  computeTaxBill: () => computeTaxBill,
+  crossOffset: () => crossOffset,
+  holdingPeriodDays: () => holdingPeriodDays,
+  isLongTerm: () => isLongTerm,
+  netWithinBucket: () => netWithinBucket,
+  realize: () => realize,
+  selectFIFO: () => selectFIFO,
+  selectHIFO: () => selectHIFO,
+  selectLIFO: () => selectLIFO,
+  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) {
+  const short = [];
+  const long = [];
+  for (const e of events) {
+    if (e.incomeKind !== "capital-gain") continue;
+    (e.termType === "long" ? long : short).push(e);
+  }
+  return { short, long };
+}
+function netWithinBucket(events) {
+  let gains = 0;
+  let losses = 0;
+  for (const e of events) {
+    if (e.gain >= 0) gains += e.gain;
+    else losses += -e.gain;
+  }
+  return { gains, losses, net: gains - losses };
+}
+function crossOffset(netShort, netLong) {
+  if (netShort >= 0 && netLong >= 0) {
+    return { taxableShort: netShort, taxableLong: netLong, ordinaryOffset: 0, carryForward: 0 };
+  }
+  if (netShort < 0 && netLong < 0) {
+    const totalLoss = -(netShort + netLong);
+    const ordinaryOffset2 = Math.min(ORDINARY_OFFSET_CAP, totalLoss);
+    return { taxableShort: 0, taxableLong: 0, ordinaryOffset: ordinaryOffset2, carryForward: totalLoss - ordinaryOffset2 };
+  }
+  const combined = netShort + netLong;
+  if (combined >= 0) {
+    const taxableShort = netShort > 0 ? combined : 0;
+    const taxableLong = netLong > 0 ? combined : 0;
+    return { taxableShort, taxableLong, ordinaryOffset: 0, carryForward: 0 };
+  }
+  const loss = -combined;
+  const ordinaryOffset = Math.min(ORDINARY_OFFSET_CAP, loss);
+  return { taxableShort: 0, taxableLong: 0, ordinaryOffset, carryForward: loss - ordinaryOffset };
+}
+function aggregateByYear(events) {
+  const out = /* @__PURE__ */ new Map();
+  const blank = () => ({
+    shortTermGains: 0,
+    shortTermLosses: 0,
+    longTermGains: 0,
+    longTermLosses: 0,
+    qualifiedDividends: 0,
+    ordinaryDividends: 0,
+    interestIncome: 0
+  });
+  for (const e of events) {
+    const year = e.closeDate.getUTCFullYear();
+    const acc = out.get(year) ?? blank();
+    switch (e.incomeKind) {
+      case "capital-gain":
+        if (e.termType === "long") {
+          if (e.gain >= 0) acc.longTermGains += e.gain;
+          else acc.longTermLosses += -e.gain;
+        } else {
+          if (e.gain >= 0) acc.shortTermGains += e.gain;
+          else acc.shortTermLosses += -e.gain;
+        }
+        break;
+      case "qualified-dividend":
+        acc.qualifiedDividends += e.proceeds;
+        break;
+      case "ordinary-dividend":
+        acc.ordinaryDividends += e.proceeds;
+        break;
+      case "interest":
+        acc.interestIncome += e.proceeds;
+        break;
+    }
+    out.set(year, acc);
+  }
+  return out;
+}
+function computeTaxBill(income, rates) {
+  const netShort = income.shortTermGains - income.shortTermLosses;
+  const netLong = income.longTermGains - income.longTermLosses;
+  const off = crossOffset(netShort, netLong);
+  const ordinaryPortion = (off.taxableShort + income.ordinaryDividends + income.interestIncome) * rates.shortTerm;
+  const ltPortion = (off.taxableLong + income.qualifiedDividends) * rates.longTerm;
+  const total = ordinaryPortion + ltPortion;
+  return { total, breakdown: { ordinaryPortion, ltPortion, carryForward: off.carryForward } };
+}
+
 // src/portfolio/derived.ts
 function positionsByAsset(portfolio) {
   const byId = /* @__PURE__ */ new Map();
@@ -3072,22 +3300,28 @@ function positionsByAsset(portfolio) {
 }
 export {
   BacktestExecutor,
+  CashEventQueue,
   Crypto24x7Calendar,
   ExchangeCalendar,
   FeatureRuntime,
   LSEExchangeCalendar,
   MemoryFeatureCache,
   NYSEExchangeCalendar,
+  ORDINARY_OFFSET_CAP,
   RoutingDataFeed,
   RoutingDataFeedError,
   RoutingQuoteFeed,
   RoutingQuoteFeedError,
   RoutingStreamingDataFeed,
   RoutingStreamingDataFeedError,
+  aggregateByYear,
   applyFills,
   applyOrders,
   barsToSeries,
+  bucketByTerm,
   collectBars,
+  computeTaxBill,
+  crossOffset,
   defineFeature,
   drawdown,
   ema,
@@ -3097,19 +3331,28 @@ export {
   fromSpec,
   getCalendar,
   getFeatureCompute,
+  holdingPeriodDays,
+  isLongTerm,
   isRebalanceDay,
+  netWithinBucket,
   paramsHash,
   periodKey,
   pollingStreamFromHistorical,
   positionsByAsset,
+  realize,
   reconcile,
   returnSeries,
   rsi,
   runBacktest,
   runLive,
+  selectFIFO,
+  selectHIFO,
+  selectLIFO,
+  selectMinTax,
   seriesAt,
   sma,
   tactical_exports as tactical,
+  tax_exports as tax,
   volatility,
   withStreamingSynthetics,
   withSynthetics