@livefolio/sdk 0.4.4 → 0.5.0-rc.2

package/dist/index.d.ts

@@ -176,6 +176,54 @@ type Position = {
     /** Optional key-value labels for strategy attribution or downstream reporting. */
     tags?: Record<string, unknown>;
 };
+/**
+ * Tax classification of a {@link RealizedEvent}. Drives which rate bucket the
+ * income falls into during year-level tax aggregation.
+ */
+type IncomeKind = 'capital-gain' | 'qualified-dividend' | 'ordinary-dividend' | 'interest';
+/**
+ * A single tax lot — one acquisition of `quantity` shares of `asset` at a
+ * point in time. The cost-basis source of truth for long holdings. Partial
+ * sales reduce `quantity` and pro-rate `basis`.
+ */
+type Lot = {
+    /** Opaque id assigned by {@link nextLotId} on creation. */
+    id: string;
+    asset: Asset;
+    /** Shares remaining in this lot after any partial sales. */
+    quantity: number;
+    /** Date the lot was opened (a DRIP lot's clock starts at its pay date). */
+    openDate: Date;
+    /** Per-share open price, excluding fees. */
+    openPrice: number;
+    /** Total cost basis for `quantity` shares incl. entry fees; pro-rated on partial sale and bumped by wash-sale §1091. */
+    basis: number;
+    /** Running total of disallowed wash-sale losses absorbed into `basis`. */
+    washSaleAdjustment?: number;
+    /** Set when this lot was created via dividend reinvestment; references the lot whose dividend funded it. */
+    dripParent?: string;
+};
+/**
+ * An append-only record of realized taxable activity: a capital gain/loss from
+ * closing (part of) a lot, or dividend/interest income. `quantity` is `0` for
+ * income events (dividends, interest), which carry `basis: 0` and `gain = proceeds`.
+ */
+type RealizedEvent = {
+    asset: Asset;
+    /** The lot this event closed against. For income events, a reference token (e.g. the paying lot, or `'cash'` for interest). */
+    lotId: string;
+    /** Shares closed; `0` for dividend and interest income events. */
+    quantity: number;
+    openDate: Date;
+    closeDate: Date;
+    proceeds: number;
+    basis: number;
+    termType: 'short' | 'long';
+    gain: number;
+    incomeKind: IncomeKind;
+    /** When `> 0`, this much of a (negative) capital gain was disallowed by the wash-sale rule and rolled into a replacement lot's basis. */
+    washSaleDisallowed?: number;
+};
 /**
  * A point-in-time snapshot of the full portfolio state.
  *
@@ -199,6 +247,17 @@ type Portfolio = {
     cash: number;
     /** All currently open positions. Immutable array — replaced (not mutated) by apply functions. */
     positions: ReadonlyArray<Position>;
+    /**
+     * Long-side tax ledger — the cost-basis source of truth for lot accounting.
+     * Maintained in parallel with `positions` by `applyFills`; defaults to `[]`
+     * when absent. Short positions and `adjust` orders do not participate.
+     */
+    lots?: ReadonlyArray<Lot>;
+    /**
+     * Append-only log of realized capital gains and dividend/interest income
+     * accumulated during a run. Defaults to `[]` when absent.
+     */
+    realized?: ReadonlyArray<RealizedEvent>;
     /** Logical timestamp of the most recent fill (or the portfolio's start date). */
     t: Date;
 };
@@ -380,6 +439,13 @@ type Fill = {
     price: number;
     /** Total transaction fees in the portfolio's base currency. */
     fees: number;
+    /**
+     * Optional id of the specific {@link Lot} this fill draws from on a sell.
+     * Set by {@link BacktestExecutor} when a `lotMethod` is configured so
+     * {@link applyFills} consumes the chosen lot rather than defaulting to FIFO.
+     * Absent on buys and on default-FIFO sells.
+     */
+    lotId?: string;
 };
 
 /**
@@ -3220,34 +3286,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 };
 }
 
 /**
@@ -3509,28 +3575,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 };
 }
 
 /**
@@ -3551,6 +3882,14 @@ declare namespace index {
  *
  * The returned `portfolio.t` is updated to the maximum fill timestamp.
  *
+ * In parallel with `positions`/`cash`, a long-side tax ledger is maintained:
+ * buys (`open` long, `rebalance` delta>0) append a {@link Lot}; sells
+ * (`close` of a long, `rebalance` delta<0) consume lots — by `fill.lotId` if
+ * present, else FIFO oldest-first — pro-rating basis and appending one
+ * {@link RealizedEvent} per consumed slice. Short positions and `adjust`
+ * orders do not participate. The `positions`/`cash` outputs are unaffected by
+ * this ledger.
+ *
  * @param portfolio - The current portfolio state before this batch.
  * @param fills     - Execution confirmations returned by {@link Executor.submit}.
  *   Each fill's `orderRef` MUST match an `id` in `orders`.
@@ -3588,6 +3927,11 @@ declare function applyFills(portfolio: Portfolio, fills: ReadonlyArray<Fill>, or
  * - `cash` is left unchanged (no price is available at projection time).
  * - Newly opened positions have `basis: 0` and `entry.price: 0` as
  *   provisional values. A price-aware projection is planned for a later phase.
+ * - The long-side tax ledger (`lots` / `realized`) is **not** advanced — it is
+ *   carried through unchanged, so it will be stale relative to the projected
+ *   `positions`. Use {@link applyFills} to settle the ledger after confirmed
+ *   execution; do not read `lots` from an `applyOrders` result expecting it to
+ *   reflect the projected positions.
  *
  * Use {@link applyFills} (not this function) to settle the portfolio after
  * confirmed execution.
@@ -3617,4 +3961,20 @@ declare function applyFills(portfolio: Portfolio, fills: ReadonlyArray<Fill>, or
  */
 declare function applyOrders(portfolio: Portfolio, orders: ReadonlyArray<Order>): Portfolio;
 
-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, LSEExchangeCalendar, type LiveEvent, 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 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, reconcile, returnSeries, rsi, runBacktest, runLive, seriesAt, sma, index$1 as tactical, volatility, withStreamingSynthetics, withSynthetics };
+/**
+ * Aggregates a portfolio's tax {@link Lot}s into a per-asset {@link Position}
+ * view (`side: 'long'`). The lot-level analogue of `portfolio.positions`,
+ * offered for consumers that want a single position per asset derived from the
+ * cost-basis ledger. `reconcile` continues to read `portfolio.positions`.
+ *
+ * The returned ids are synthetic view keys (`lot_view_<assetId>`) — they are
+ * NOT stable `PositionId`s and must not be passed to `CloseOrder.positionId`
+ * or compared against `portfolio.positions[*].id`.
+ *
+ * @param portfolio - Source portfolio; reads `portfolio.lots` (treated as `[]` when absent).
+ * @returns One {@link Position} per distinct asset id, summing quantity and basis,
+ *   with `entry` taken from the earliest lot. Empty when there are no lots.
+ */
+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 };