@livefolio/sdk 0.5.0-rc.1 → 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
@@ -3286,34 +3366,34 @@ declare function isRebalanceDay(t: Date, freq: RebalanceFrequency, calendar: Cal
  */
 declare function fromSpec(spec: TacticalSpec, opts: FromSpecOptions): Strategy<TacticalFeatures, RuleTreeState>;
 
-type index$1_AllocateNode = AllocateNode;
-type index$1_AssetRef = AssetRef;
-type index$1_Comparison = Comparison;
-type index$1_ComparisonOp = ComparisonOp;
-type index$1_FeatureRef = FeatureRef;
-type index$1_FromSpecOptions = FromSpecOptions;
-type index$1_IfNode = IfNode;
-type index$1_RebalanceConfig = RebalanceConfig;
-type index$1_RebalanceFrequency = RebalanceFrequency;
-type index$1_RuleNode = RuleNode;
-type index$1_RuleTreeState = RuleTreeState;
-type index$1_SyntheticAsset = SyntheticAsset;
-type index$1_TacticalFeatureKind = TacticalFeatureKind;
-type index$1_TacticalFeatureSpec = TacticalFeatureSpec;
-type index$1_TacticalFeatures = TacticalFeatures;
-type index$1_TacticalSpec = TacticalSpec;
-type index$1_Tolerance = Tolerance;
-type index$1_WithStreamingSyntheticsOptions = WithStreamingSyntheticsOptions;
-declare const index$1__resetTacticalDeprecationWarningForTesting: typeof _resetTacticalDeprecationWarningForTesting;
-declare const index$1_evaluateFeatureSpecs: typeof evaluateFeatureSpecs;
-declare const index$1_evaluateRuleTree: typeof evaluateRuleTree;
-declare const index$1_fromSpec: typeof fromSpec;
-declare const index$1_isRebalanceDay: typeof isRebalanceDay;
-declare const index$1_periodKey: typeof periodKey;
-declare const index$1_withStreamingSynthetics: typeof withStreamingSynthetics;
-declare const index$1_withSynthetics: typeof withSynthetics;
-declare namespace index$1 {
-  export { type index$1_AllocateNode as AllocateNode, type index$1_AssetRef as AssetRef, type index$1_Comparison as Comparison, type index$1_ComparisonOp as ComparisonOp, type index$1_FeatureRef as FeatureRef, type index$1_FromSpecOptions as FromSpecOptions, type index$1_IfNode as IfNode, type index$1_RebalanceConfig as RebalanceConfig, type index$1_RebalanceFrequency as RebalanceFrequency, type index$1_RuleNode as RuleNode, type index$1_RuleTreeState as RuleTreeState, type index$1_SyntheticAsset as SyntheticAsset, type index$1_TacticalFeatureKind as TacticalFeatureKind, type index$1_TacticalFeatureSpec as TacticalFeatureSpec, type index$1_TacticalFeatures as TacticalFeatures, type index$1_TacticalSpec as TacticalSpec, type index$1_Tolerance as Tolerance, type index$1_WithStreamingSyntheticsOptions as WithStreamingSyntheticsOptions, index$1__resetTacticalDeprecationWarningForTesting as _resetTacticalDeprecationWarningForTesting, index$1_evaluateFeatureSpecs as evaluateFeatureSpecs, index$1_evaluateRuleTree as evaluateRuleTree, index$1_fromSpec as fromSpec, index$1_isRebalanceDay as isRebalanceDay, index$1_periodKey as periodKey, index$1_withStreamingSynthetics as withStreamingSynthetics, index$1_withSynthetics as withSynthetics };
+type index$2_AllocateNode = AllocateNode;
+type index$2_AssetRef = AssetRef;
+type index$2_Comparison = Comparison;
+type index$2_ComparisonOp = ComparisonOp;
+type index$2_FeatureRef = FeatureRef;
+type index$2_FromSpecOptions = FromSpecOptions;
+type index$2_IfNode = IfNode;
+type index$2_RebalanceConfig = RebalanceConfig;
+type index$2_RebalanceFrequency = RebalanceFrequency;
+type index$2_RuleNode = RuleNode;
+type index$2_RuleTreeState = RuleTreeState;
+type index$2_SyntheticAsset = SyntheticAsset;
+type index$2_TacticalFeatureKind = TacticalFeatureKind;
+type index$2_TacticalFeatureSpec = TacticalFeatureSpec;
+type index$2_TacticalFeatures = TacticalFeatures;
+type index$2_TacticalSpec = TacticalSpec;
+type index$2_Tolerance = Tolerance;
+type index$2_WithStreamingSyntheticsOptions = WithStreamingSyntheticsOptions;
+declare const index$2__resetTacticalDeprecationWarningForTesting: typeof _resetTacticalDeprecationWarningForTesting;
+declare const index$2_evaluateFeatureSpecs: typeof evaluateFeatureSpecs;
+declare const index$2_evaluateRuleTree: typeof evaluateRuleTree;
+declare const index$2_fromSpec: typeof fromSpec;
+declare const index$2_isRebalanceDay: typeof isRebalanceDay;
+declare const index$2_periodKey: typeof periodKey;
+declare const index$2_withStreamingSynthetics: typeof withStreamingSynthetics;
+declare const index$2_withSynthetics: typeof withSynthetics;
+declare namespace index$2 {
+  export { type index$2_AllocateNode as AllocateNode, type index$2_AssetRef as AssetRef, type index$2_Comparison as Comparison, type index$2_ComparisonOp as ComparisonOp, type index$2_FeatureRef as FeatureRef, type index$2_FromSpecOptions as FromSpecOptions, type index$2_IfNode as IfNode, type index$2_RebalanceConfig as RebalanceConfig, type index$2_RebalanceFrequency as RebalanceFrequency, type index$2_RuleNode as RuleNode, type index$2_RuleTreeState as RuleTreeState, type index$2_SyntheticAsset as SyntheticAsset, type index$2_TacticalFeatureKind as TacticalFeatureKind, type index$2_TacticalFeatureSpec as TacticalFeatureSpec, type index$2_TacticalFeatures as TacticalFeatures, type index$2_TacticalSpec as TacticalSpec, type index$2_Tolerance as Tolerance, type index$2_WithStreamingSyntheticsOptions as WithStreamingSyntheticsOptions, index$2__resetTacticalDeprecationWarningForTesting as _resetTacticalDeprecationWarningForTesting, index$2_evaluateFeatureSpecs as evaluateFeatureSpecs, index$2_evaluateRuleTree as evaluateRuleTree, index$2_fromSpec as fromSpec, index$2_isRebalanceDay as isRebalanceDay, index$2_periodKey as periodKey, index$2_withStreamingSynthetics as withStreamingSynthetics, index$2_withSynthetics as withSynthetics };
 }
 
 /**
@@ -3575,28 +3655,293 @@ declare function volatility(series: Series, period: number): Series;
  */
 declare function drawdown(series: Series, period: number): Series;
 
-type index_BarField = BarField;
-type index_ComputeFn = ComputeFn;
-type index_FeatureKind = FeatureKind;
-type index_FeatureRuntime = FeatureRuntime;
-declare const index_FeatureRuntime: typeof FeatureRuntime;
-type index_FeatureRuntimeOptions = FeatureRuntimeOptions;
-type index_FeatureSpec = FeatureSpec;
-type index_ReturnMode = ReturnMode;
-declare const index_barsToSeries: typeof barsToSeries;
-declare const index_collectBars: typeof collectBars;
-declare const index_defineFeature: typeof defineFeature;
-declare const index_drawdown: typeof drawdown;
-declare const index_ema: typeof ema;
-declare const index_getFeatureCompute: typeof getFeatureCompute;
-declare const index_paramsHash: typeof paramsHash;
-declare const index_returnSeries: typeof returnSeries;
-declare const index_rsi: typeof rsi;
-declare const index_seriesAt: typeof seriesAt;
-declare const index_sma: typeof sma;
-declare const index_volatility: typeof volatility;
+type index$1_BarField = BarField;
+type index$1_ComputeFn = ComputeFn;
+type index$1_FeatureKind = FeatureKind;
+type index$1_FeatureRuntime = FeatureRuntime;
+declare const index$1_FeatureRuntime: typeof FeatureRuntime;
+type index$1_FeatureRuntimeOptions = FeatureRuntimeOptions;
+type index$1_FeatureSpec = FeatureSpec;
+type index$1_ReturnMode = ReturnMode;
+declare const index$1_barsToSeries: typeof barsToSeries;
+declare const index$1_collectBars: typeof collectBars;
+declare const index$1_defineFeature: typeof defineFeature;
+declare const index$1_drawdown: typeof drawdown;
+declare const index$1_ema: typeof ema;
+declare const index$1_getFeatureCompute: typeof getFeatureCompute;
+declare const index$1_paramsHash: typeof paramsHash;
+declare const index$1_returnSeries: typeof returnSeries;
+declare const index$1_rsi: typeof rsi;
+declare const index$1_seriesAt: typeof seriesAt;
+declare const index$1_sma: typeof sma;
+declare const index$1_volatility: typeof volatility;
+declare namespace index$1 {
+  export { type index$1_BarField as BarField, type index$1_ComputeFn as ComputeFn, type index$1_FeatureKind as FeatureKind, index$1_FeatureRuntime as FeatureRuntime, type index$1_FeatureRuntimeOptions as FeatureRuntimeOptions, type index$1_FeatureSpec as FeatureSpec, type index$1_ReturnMode as ReturnMode, index$1_barsToSeries as barsToSeries, index$1_collectBars as collectBars, index$1_defineFeature as defineFeature, index$1_drawdown as drawdown, index$1_ema as ema, index$1_getFeatureCompute as getFeatureCompute, index$1_paramsHash as paramsHash, index$1_returnSeries as returnSeries, index$1_rsi as rsi, index$1_seriesAt as seriesAt, index$1_sma as sma, index$1_volatility as volatility };
+}
+
+/**
+ * Calendar days between a lot's open date and `asOf` (float; may be fractional
+ * or negative if `asOf` precedes `openDate`). Callers may `Math.floor` it.
+ */
+declare function holdingPeriodDays(lot: Lot, asOf: Date): number;
+/** IRS §1222 rule: a holding period of strictly more than 365 calendar days is long-term. */
+declare function isLongTerm(days: number): boolean;
+/** Result of {@link realize}: the realized event plus what's left of the lot (`null` on a full sale). */
+type RealizeResult = {
+    event: RealizedEvent;
+    remainingLot: Lot | null;
+};
+/**
+ * Realizes `qty` shares of `lot` at `salePrice` as of `asOf`, producing one
+ * {@link RealizedEvent} and the remaining lot (or `null` on a full sale).
+ *
+ * Pure gain/loss primitive for estimation and lot ranking (e.g. selectMinTax,
+ * TLH preview). It does **not** model transaction fees: pass a `salePrice` that
+ * is already net of any per-share fee if you need fee-adjusted proceeds. The
+ * stateful, fee-aware realization path used during execution lives in
+ * `applyFills` (`consumeLots`), which pro-rates `fill.fees` across slices.
+ *
+ * Basis is pro-rated as `lot.basis / lot.quantity * qty` (so any
+ * `washSaleAdjustment` already folded into `lot.basis` is carried through).
+ *
+ * @param lot - The lot to realize against.
+ * @param qty - Shares to realize. Must be `> 0` and `<= lot.quantity`.
+ * @param salePrice - Per-share sale price (net of fees if fee-adjustment is desired).
+ * @param asOf - Sale date; drives short/long classification via the 365-day rule.
+ * @returns `{ event, remainingLot }`; `remainingLot` is `null` when the whole lot is sold.
+ * @throws {RangeError} if `qty <= 0` or `qty > lot.quantity`.
+ */
+declare function realize(lot: Lot, qty: number, salePrice: number, asOf: Date): RealizeResult;
+
+/** A slice of a tax lot consumed to fulfill part of a sell order. */
+type LotSlice = {
+    lotId: string;
+    quantity: number;
+};
+/** Short-term and long-term capital-gains tax rates (as decimals, e.g. 0.37). */
+type TaxRates = {
+    shortTerm: number;
+    longTerm: number;
+};
+/**
+ * First-In-First-Out lot selection.
+ *
+ * Selects lots in ascending `openDate` order, consuming oldest lots first.
+ */
+declare function selectFIFO(lots: readonly Lot[], qty: number): LotSlice[];
+/**
+ * Last-In-First-Out lot selection.
+ *
+ * Selects lots in descending `openDate` order, consuming newest lots first.
+ */
+declare function selectLIFO(lots: readonly Lot[], qty: number): LotSlice[];
+/**
+ * Highest-In-First-Out lot selection.
+ *
+ * Selects lots in descending per-share basis (`basis / quantity`) order,
+ * realizing the highest-cost lots first to minimize gains.
+ */
+declare function selectHIFO(lots: readonly Lot[], qty: number): LotSlice[];
+/**
+ * Tax-minimizing lot selection.
+ *
+ * Ranks lots by a 4-tier comparator designed to realize the least tax:
+ * 1. Long-term losses  (tier 0) — offsets LT gains at the lower LT rate
+ * 2. Short-term losses (tier 1) — offsets ST gains at the higher ST rate
+ * 3. Long-term gains   (tier 2) — taxed at the lower LT rate
+ * 4. Short-term gains  (tier 3) — taxed at the higher ST rate
+ *
+ * Within a tier, lots are sorted by ascending gain-per-share so that the
+ * largest losses (or smallest gains) are consumed first.
+ *
+ * Uses `isLongTerm(holdingPeriodDays(lot, ctx.asOf))` for term classification
+ * and `ctx.price - lot.basis / lot.quantity` for gain-per-share.
+ *
+ * `ctx.rates` is accepted for forward-compatibility and signature stability
+ * (the executor's min-tax `lotMethod` passes it through); the current 4-tier
+ * ranking does not read the rate magnitudes.
+ *
+ * NOTE: this is a conservative, IRS-aligned *ordering* heuristic, not a literal
+ * rate-weighted per-share tax minimum. The two can diverge: a $100/share LT gain
+ * (tier 2, $20 tax at a 20% LT rate) is selected before a $50/share ST gain
+ * (tier 3, $18.50 tax at a 37% ST rate), even though the ST lot realizes less
+ * tax. The tier order favors the lower-rate bucket and sidesteps marginal-bracket
+ * complexity; it does not compute `gain × rate` per lot.
+ */
+declare function selectMinTax(lots: readonly Lot[], qty: number, ctx: {
+    price: number;
+    asOf: Date;
+    rates: TaxRates;
+}): LotSlice[];
+
+/**
+ * Maximum capital-loss deduction against ordinary income per IRS §1211(b).
+ * In a given tax year, net capital losses above `ORDINARY_OFFSET_CAP` are
+ * carried forward to future years rather than deducted immediately.
+ */
+declare const ORDINARY_OFFSET_CAP = 3000;
+/**
+ * Year-level summary of taxable income across all categories.
+ *
+ * - `shortTermGains` / `longTermGains`: sum of positive `gain` values from
+ *   capital-gain events in each term bucket.
+ * - `shortTermLosses` / `longTermLosses`: sum of |negative `gain`| values
+ *   (stored as **positive magnitudes**) from capital-gain events.
+ * - `qualifiedDividends`: qualified dividend income (taxed at LT rate).
+ * - `ordinaryDividends`: non-qualified dividend income (taxed at ST rate).
+ * - `interestIncome`: interest income (taxed at ST rate).
+ *
+ * Capital losses **never** offset `qualifiedDividends` or `ordinaryDividends`.
+ * The cross-offset logic in {@link crossOffset} operates only on the capital-
+ * gain buckets; dividend/interest income is added post-offset at full value.
+ */
+type TaxableIncome = {
+    shortTermGains: number;
+    /** Positive magnitude of short-term capital losses. */
+    shortTermLosses: number;
+    longTermGains: number;
+    /** Positive magnitude of long-term capital losses. */
+    longTermLosses: number;
+    qualifiedDividends: number;
+    ordinaryDividends: number;
+    interestIncome: number;
+};
+/**
+ * Partitions `events` into short-term and long-term capital-gain buckets.
+ *
+ * Events with `incomeKind !== 'capital-gain'` (dividends, interest) are
+ * excluded entirely — they are not subject to the capital-gain offset logic.
+ *
+ * @param events - Flat array of {@link RealizedEvent}s for a single year or
+ *   for the full history (caller selects the relevant slice).
+ * @returns `{ short, long }` — two arrays of capital-gain events by term.
+ */
+declare function bucketByTerm(events: readonly RealizedEvent[]): {
+    short: RealizedEvent[];
+    long: RealizedEvent[];
+};
+/**
+ * Nets gains and losses within a single bucket (all-short or all-long).
+ *
+ * Events with `gain >= 0` contribute to `gains`; events with `gain < 0`
+ * contribute to `losses` as a **positive magnitude**.
+ *
+ * @param events - Capital-gain events for one term bucket.
+ * @returns `{ gains, losses, net }` where `net = gains - losses`.
+ */
+declare function netWithinBucket(events: readonly RealizedEvent[]): {
+    gains: number;
+    losses: number;
+    net: number;
+};
+/**
+ * Applies IRS capital-gain cross-offset rules between short-term and long-term nets.
+ *
+ * Rules (in order of precedence):
+ * 1. **Both non-negative**: no offset; return each net unchanged.
+ * 2. **Both negative**: combine losses; apply up to `ORDINARY_OFFSET_CAP` ($3,000)
+ *    against ordinary income; remainder becomes `carryForward`.
+ * 3. **Opposite signs, combined ≥ 0**: the loss bucket fully absorbs into the gain
+ *    bucket; the residual stays in the gain bucket's term (`taxableShort` if
+ *    `netShort > 0`, else `taxableLong`). No ordinary offset or carry-forward.
+ * 4. **Opposite signs, combined < 0**: net loss after cross-offset;
+ *    up to `ORDINARY_OFFSET_CAP` deducted against ordinary income; remainder
+ *    becomes `carryForward`.
+ *
+ * **Important:** `ordinaryOffset` and `carryForward` apply only to capital
+ * losses. Dividend and interest income is never offset by capital losses.
+ *
+ * @param netShort - Net short-term capital gain (negative = loss).
+ * @param netLong  - Net long-term capital gain (negative = loss).
+ * @returns `{ taxableShort, taxableLong, ordinaryOffset, carryForward }`.
+ */
+declare function crossOffset(netShort: number, netLong: number): {
+    taxableShort: number;
+    taxableLong: number;
+    ordinaryOffset: number;
+    carryForward: number;
+};
+/**
+ * Aggregates {@link RealizedEvent}s by UTC calendar year into a
+ * {@link TaxableIncome} map.
+ *
+ * Keyed by `closeDate.getUTCFullYear()`. Each event is routed:
+ * - `capital-gain`: bucketed into `shortTermGains`/`shortTermLosses` (ST) or
+ *   `longTermGains`/`longTermLosses` (LT) by `termType` and sign of `gain`.
+ *   Losses are stored as **positive magnitudes**.
+ * - `qualified-dividend`: adds `proceeds` to `qualifiedDividends`.
+ * - `ordinary-dividend`: adds `proceeds` to `ordinaryDividends`.
+ * - `interest`: adds `proceeds` to `interestIncome`.
+ *
+ * Year boundaries use **UTC**. Backtests are unambiguous (daily bars are
+ * UTC-midnight-anchored). Live-mode callers should normalize `closeDate` to the
+ * tax jurisdiction's local time before passing events here if they need
+ * calendar-year precision around year-end — e.g. a US fill on Dec 31 evening
+ * Eastern has a UTC `closeDate` of Jan 1, which belongs to the *prior* US tax
+ * year but would otherwise be counted in the next year.
+ *
+ * @param events - Full sequence of realized events (multiple years OK).
+ * @returns `Map<year, TaxableIncome>` with one entry per UTC calendar year.
+ */
+declare function aggregateByYear(events: readonly RealizedEvent[]): Map<number, TaxableIncome>;
+/**
+ * Computes the tax bill for a single year's {@link TaxableIncome}.
+ *
+ * Steps:
+ * 1. Net each capital-gain bucket: `netShort = shortTermGains - shortTermLosses`,
+ *    `netLong = longTermGains - longTermLosses`.
+ * 2. Apply {@link crossOffset} to get `taxableShort`, `taxableLong`,
+ *    `ordinaryOffset`, and `carryForward`.
+ * 3. `ordinaryPortion = (taxableShort + ordinaryDividends + interestIncome) * shortTerm`.
+ * 4. `ltPortion = (taxableLong + qualifiedDividends) * longTerm`.
+ * 5. `total = ordinaryPortion + ltPortion`.
+ *
+ * **Critical invariant:** capital losses do **not** offset `qualifiedDividends`.
+ * Qualified dividends are added to the LT pool *after* cross-offset, at their
+ * full value, so a LT capital loss that wipes out `taxableLong` to zero still
+ * leaves the qualified dividend income fully taxable at the LT rate.
+ *
+ * `carryForward` is surfaced as a return field for the caller to track across
+ * years; this function does **not** consume carry-forward from prior years
+ * (cross-year carry is V3 work).
+ *
+ * Note: the `ordinaryOffset` produced by {@link crossOffset} (the up-to-$3,000
+ * §1211(b) capital-loss deduction against ordinary income) is intentionally not
+ * surfaced here. This function models only the tax on capital income; that
+ * deduction applies against wage/business income outside this module's scope.
+ *
+ * @param income - Year-level taxable income, as produced by {@link aggregateByYear}.
+ * @param rates  - `{ shortTerm, longTerm }` tax rates as decimals (e.g. `0.37`).
+ * @returns `{ total, breakdown: { ordinaryPortion, ltPortion, carryForward } }`.
+ */
+declare function computeTaxBill(income: TaxableIncome, rates: TaxRates): {
+    total: number;
+    breakdown: {
+        ordinaryPortion: number;
+        ltPortion: number;
+        carryForward: number;
+    };
+};
+
+type index_LotSlice = LotSlice;
+declare const index_ORDINARY_OFFSET_CAP: typeof ORDINARY_OFFSET_CAP;
+type index_RealizeResult = RealizeResult;
+type index_TaxRates = TaxRates;
+type index_TaxableIncome = TaxableIncome;
+declare const index_aggregateByYear: typeof aggregateByYear;
+declare const index_bucketByTerm: typeof bucketByTerm;
+declare const index_computeTaxBill: typeof computeTaxBill;
+declare const index_crossOffset: typeof crossOffset;
+declare const index_holdingPeriodDays: typeof holdingPeriodDays;
+declare const index_isLongTerm: typeof isLongTerm;
+declare const index_netWithinBucket: typeof netWithinBucket;
+declare const index_realize: typeof realize;
+declare const index_selectFIFO: typeof selectFIFO;
+declare const index_selectHIFO: typeof selectHIFO;
+declare const index_selectLIFO: typeof selectLIFO;
+declare const index_selectMinTax: typeof selectMinTax;
 declare namespace index {
-  export { type index_BarField as BarField, type index_ComputeFn as ComputeFn, type index_FeatureKind as FeatureKind, index_FeatureRuntime as FeatureRuntime, type index_FeatureRuntimeOptions as FeatureRuntimeOptions, type index_FeatureSpec as FeatureSpec, type index_ReturnMode as ReturnMode, index_barsToSeries as barsToSeries, index_collectBars as collectBars, index_defineFeature as defineFeature, index_drawdown as drawdown, index_ema as ema, index_getFeatureCompute as getFeatureCompute, index_paramsHash as paramsHash, index_returnSeries as returnSeries, index_rsi as rsi, index_seriesAt as seriesAt, index_sma as sma, index_volatility as volatility };
+  export { type index_LotSlice as LotSlice, index_ORDINARY_OFFSET_CAP as ORDINARY_OFFSET_CAP, type index_RealizeResult as RealizeResult, type index_TaxRates as TaxRates, type index_TaxableIncome as TaxableIncome, index_aggregateByYear as aggregateByYear, index_bucketByTerm as bucketByTerm, index_computeTaxBill as computeTaxBill, index_crossOffset as crossOffset, index_holdingPeriodDays as holdingPeriodDays, index_isLongTerm as isLongTerm, index_netWithinBucket as netWithinBucket, index_realize as realize, index_selectFIFO as selectFIFO, index_selectHIFO as selectHIFO, index_selectLIFO as selectLIFO, index_selectMinTax as selectMinTax };
 }
 
 /**
@@ -3712,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 MacroAsset, MemoryFeatureCache, NYSEExchangeCalendar, type NextOpenFn, type OpenOrder, type Order, type PollingSchedule, type PollingStreamOptions, type Portfolio, type Position, type PositionId, type PriceMap, type Quote, type QuoteFeed, 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 TimeOfDay, type Tolerance, type WithStreamingSyntheticsOptions, applyFills, applyOrders, barsToSeries, collectBars, defineFeature, drawdown, ema, evaluateFeatureSpecs, evaluateRuleTree, index as features, fromSpec, getCalendar, getFeatureCompute, isRebalanceDay, paramsHash, periodKey, pollingStreamFromHistorical, positionsByAsset, reconcile, returnSeries, rsi, runBacktest, runLive, seriesAt, sma, index$1 as tactical, 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 };