@livefolio/sdk 0.3.7 → 0.4.0

package/dist/index.d.ts

@@ -1,732 +1,3396 @@
-interface MarketProvider {
-    fetchBars(symbol: string, from?: string): Promise<DailyBar[]>;
-}
+/**
+ * Stable string identifier for an asset. Matches the `id` field of {@link Asset}.
+ * Use this type when you only need to key or compare assets without carrying
+ * the full {@link Asset} object.
+ */
+type AssetId = string;
+/**
+ * An equity instrument — common stock or ETF.
+ *
+ * @example
+ * ```ts
+ * const aapl: EquityAsset = {
+ *   kind: 'equity',
+ *   id: 'AAPL',
+ *   symbol: 'AAPL',
+ *   exchange: 'NASDAQ',
+ * };
+ * ```
+ */
+type EquityAsset = {
+    kind: 'equity';
+    /** Stable opaque ID — typically the ticker, but treat as opaque. */
+    id: AssetId;
+    /** Display symbol, e.g. `'AAPL'`. */
+    symbol: string;
+    /** MIC or common exchange name, e.g. `'NYSE'`, `'NASDAQ'`. Optional. */
+    exchange?: string;
+};
+/**
+ * A macroeconomic time series — e.g. a FRED series like `DGS10` (10-year
+ * Treasury yield) or `CPIAUCSL` (CPI, all items). Models single-value series
+ * as bars whose OHLC are equal to the published value.
+ *
+ * @example
+ * ```ts
+ * const dgs10: MacroAsset = {
+ *   kind: 'macro',
+ *   id: 'DGS10',
+ *   symbol: '10Y Treasury',
+ *   source: 'FRED',
+ * };
+ * ```
+ */
+type MacroAsset = {
+    kind: 'macro';
+    /** Provider-scoped series ID, e.g. `'DGS10'`, `'CPIAUCSL'`. */
+    id: AssetId;
+    /** Human-readable label, e.g. `'10Y Treasury'`, `'CPI'`. */
+    symbol: string;
+    /** Data provider tag, e.g. `'FRED'`. Optional. */
+    source?: string;
+};
+/**
+ * A tradeable or queryable instrument. Discriminated by `kind`. Add a new
+ * variant to this union when introducing a new asset class (futures, option,
+ * crypto, etc.); each variant is the natural narrowing point for vendor-
+ * specific fields.
+ */
+type Asset = EquityAsset | MacroAsset;
+/**
+ * Bar granularity. Determines the width of each {@link Bar} returned by
+ * {@link DataFeed.bars}.
+ *
+ * - `'1m'`  — one-minute bars
+ * - `'5m'`  — five-minute bars
+ * - `'15m'` — fifteen-minute bars
+ * - `'1h'`  — hourly bars
+ * - `'1d'`  — daily bars (most common for end-of-day strategies)
+ */
+type Frequency = '1m' | '5m' | '15m' | '1h' | '1d';
+/**
+ * Half-open calendar interval `[from, to)`. Used throughout the SDK wherever
+ * a date range is required. `from` is inclusive; `to` is exclusive.
+ *
+ * @example
+ * ```ts
+ * import type { DateRange } from '@livefolio/sdk';
+ *
+ * const range: DateRange = {
+ *   from: new Date('2024-01-01'),
+ *   to:   new Date('2025-01-01'),
+ * };
+ * ```
+ */
+type DateRange = {
+    /** Inclusive start of the range. */
+    from: Date;
+    /** Exclusive end of the range. */
+    to: Date;
+};
+/**
+ * A single OHLCV bar for one asset at one point in time.
+ *
+ * @example
+ * ```ts
+ * import type { Bar } from '@livefolio/sdk';
+ *
+ * // Typical daily bar for a $150 stock
+ * const bar: Bar = {
+ *   t:      new Date('2024-06-01'),
+ *   open:   150.0,
+ *   high:   153.4,
+ *   low:    149.1,
+ *   close:  152.7,
+ *   volume: 8_500_000,
+ * };
+ * ```
+ */
+type Bar = {
+    /** Bar timestamp (opening instant for intraday bars; midnight UTC for daily). */
+    t: Date;
+    open: number;
+    high: number;
+    low: number;
+    close: number;
+    /** Total shares traded during the bar period. */
+    volume: number;
+};
+/**
+ * An ordered time series of scalar values. Used as the output type of feature
+ * computations and as the storage unit in {@link FeatureCache}.
+ *
+ * Each element pairs a timestamp `t` with a numeric value `v`. The array is
+ * `ReadonlyArray`, so implementations must not mutate it after construction.
+ */
+type Series = ReadonlyArray<{
+    t: Date;
+    v: number;
+}>;
 
-type IndicatorType = 'Price' | 'SMA' | 'EMA' | 'RSI' | 'Return' | 'Volatility' | 'Drawdown' | 'VIX' | 'VIX3M' | 'T3M' | 'T6M' | 'T1Y' | 'T2Y' | 'T3Y' | 'T5Y' | 'T7Y' | 'T10Y' | 'T20Y' | 'T30Y' | 'Month' | 'Day of Week' | 'Day of Month' | 'Day of Year' | 'Threshold';
-type TradingFreq = 'Daily' | 'Weekly' | 'Monthly' | 'Bi-monthly' | 'Quarterly' | 'Every 4 Months' | 'Semiannually' | 'Yearly';
-type Comparison = '>' | '<' | '=';
-type Unit = '%' | 'bps' | 'std';
-interface StrategySeriesEntry {
-    date: string;
-    allocationId: number;
-}
-interface StrategyRuleDefinition {
-    signalIds?: number[];
-    allocationId: number;
-}
-interface StrategyDefinition {
-    linkId: string;
-    name: string;
-    freq: TradingFreq;
-    offset: number;
-    rules: StrategyRuleDefinition[];
-}
-interface StrategyReferenceData {
-    id: number;
-    name: string;
-    freq: TradingFreq;
-    offset: number;
-    rules: {
-        signals: {
-            id: number;
-            indicatorId1: number;
-            indicatorId2: number;
-            comparison: Comparison;
-            tolerance: number;
-        }[];
-        allocations: {
-            id: number;
-            holdings: Record<string, number>;
-        }[];
-        indicators: {
-            id: number;
-            type: IndicatorType;
-            tickerId: number | null;
-            lookback: number;
-            delay: number;
-            unit: Unit | null;
-            threshold: number | null;
-        }[];
-        tickers: {
-            id: number;
-            symbol: string;
-            leverage: number;
-        }[];
-        definition: StrategyRuleDefinition[];
+/**
+ * Stable opaque string identifier for a {@link Position}. Generated by the
+ * SDK when a position is opened; callers should treat this as an opaque key
+ * and not parse its contents.
+ */
+type PositionId = string;
+/**
+ * A single open position in an asset.
+ *
+ * `basis` tracks the total cost of the position (including fees) and is used
+ * for realized P&L calculations. It is updated by `applyFills` as the
+ * position is added to or reduced.
+ *
+ * @example
+ * ```ts
+ * import type { Position } from '@livefolio/sdk';
+ *
+ * const pos: Position = {
+ *   id:       'pos_1',
+ *   asset:    { kind: 'equity', id: 'AAPL', symbol: 'AAPL' },
+ *   side:     'long',
+ *   quantity: 100,
+ *   entry:    { date: new Date('2024-01-02'), price: 185.5 },
+ *   basis:    18_550.50,  // quantity * price + fees
+ *   tags:     { strategy: 'momentum' },
+ * };
+ * ```
+ */
+type Position = {
+    /** Stable opaque ID assigned when the position was opened. */
+    id: PositionId;
+    asset: Asset;
+    side: 'long' | 'short';
+    /** Current number of shares (or units) held. */
+    quantity: number;
+    /** Price and date at which this position lot was initially opened. */
+    entry: {
+        date: Date;
+        price: number;
     };
-}
-
-declare class TickerHandle {
-    readonly symbol: string;
-    readonly leverage: number;
-    private _storage;
-    private _resolvedId;
-    private _resolving;
-    constructor(storage: StorageProvider, symbol: string, leverage?: number);
-    get id(): number;
-    resolve(): Promise<{
-        id: number;
-    }>;
-    static fromResolved(storage: StorageProvider, id: number, symbol: string, leverage: number): TickerHandle;
-    private _doResolve;
-}
-
-interface DailyBar {
-    date: string;
-    value: number;
-}
-interface IndicatorIdentity {
-    type: IndicatorType;
-    ticker: TickerHandle | null;
-    lookback: number;
-    delay: number;
-    unit: Unit | null;
-    threshold: number | null;
-}
-interface DateRange {
-    from?: string;
-    to?: string;
-}
-declare class IndicatorHandle {
-    readonly type: IndicatorType;
-    readonly ticker: TickerHandle | null;
-    readonly lookback: number;
-    readonly delay: number;
-    readonly unit: Unit | null;
-    readonly threshold: number | null;
-    private _storage;
-    private _market;
-    private _resolvedId;
-    private _resolving;
-    private _cachedSeries;
-    private _cachedAsOf;
-    private _syncing;
-    constructor(storage: StorageProvider, market: MarketProvider, identity: IndicatorIdentity);
-    get id(): number;
-    resolve(): Promise<{
-        id: number;
-    }>;
-    static fromResolved(storage: StorageProvider, market: MarketProvider, id: number, identity: IndicatorIdentity): IndicatorHandle;
-    private _doResolve;
-    private _getLatestClosedTradingDay;
-    private _getLatestSeriesDate;
-    private _ensureFresh;
-    private _sync;
-    private _fetchRawBarsForIncremental;
-    private _upsertSeries;
-    private _querySeriesFromDb;
-    /**
-     * Apply leverage compounding to a raw bar series, anchored to a stored
-     * leveraged value. Used by both `_sync` and `computeAt` so they stay
-     * consistent.
-     *
-     * `anchorDate` is the date of the last *already-stored* leveraged bar
-     * (i.e., the bar just before `rawBars[0]`). The stored leveraged value
-     * at that date becomes `leveraged[0]`; raw returns are then compounded
-     * forward for each subsequent bar.
-     *
-     * If no stored anchor exists (first-ever sync), falls back to rawBars[0]
-     * as the starting raw value — identical to `_sync`'s behaviour.
-     */
-    private _applyLeverage;
-    /**
-     * Compute the indicator's value at `date` without persisting anything, with
-     * optional live-quote `overrides` keyed by raw market symbol (the same symbol
-     * space `MarketProvider.fetchBars` uses — ticker symbols for Price/SMA/etc.,
-     * `^VIX` / `^VIX3M` for macro, FRED series IDs like `DGS3MO` for Treasury).
-     *
-     * Bars for the underlying symbol are resolved storage-first when the market
-     * hasn't yet produced bars for `date` (trading day still open), and storage
-     * is the fallback whenever the remote fetch fails — see `_resolveRawBars`.
-     *
-     * For Threshold: returns the threshold constant. For calendar types: computed
-     * from `tradingDays.getRange()`. For all others: `_resolveRawBars` → leverage
-     * compounding (if any) → lookback-specific computation. Returns null if the
-     * value cannot be computed.
-     */
-    computeAt(date: string, overrides?: Record<string, number>): Promise<number | null>;
-    /**
-     * Raw (unleveraged) bars for `symbol` up through `date`, with the live quote
-     * from `overrides[symbol]` (if any) spliced in at `date`.
-     *
-     * Decision policy:
-     *   - `date` > `tradingDays.getLatestClosed()`: market has nothing for that
-     *     day yet — skip the remote fetch entirely and read from storage.
-     *   - otherwise: try `this._market.fetchBars(symbol, from)`. On failure, fall
-     *     back to storage — upstream HTTP providers (Yahoo / FRED) are flaky.
-     *
-     * After the base is resolved, `overrides[symbol]` is spliced at `date`
-     * (replaces the existing bar, or is appended in-order). When no override is
-     * present but `date` isn't in the base bars, the last known value is carried
-     * forward to `date` — this preserves the fallbackMissingQuotes behaviour the
-     * old overlay exposed so leverage compounding / computations always have a
-     * point at `date` to land on.
-     */
-    private _resolveRawBars;
-    /**
-     * Resolve the single raw (unleveraged) value for `symbol` at `date`.
-     * Returns the override directly when present; otherwise delegates to
-     * `_resolveRawBars` with a one-day window and picks the matching bar.
-     */
-    private _resolveRawBarAt;
-    /**
-     * Resolve raw (unleveraged) bars for a market symbol from storage. Maps:
-     *   - `^VIX`   → the VIX indicator's stored series
-     *   - `^VIX3M` → the VIX3M indicator's stored series
-     *   - `DGS*`   → the matching Treasury-tenor indicator's stored series
-     *   - anything else → the `Price` indicator for that ticker symbol with
-     *     `leverage = 1` (the raw contract that `MarketProvider.fetchBars` has).
-     *
-     * Returns `[]` when the resolved indicator has no stored bars yet.
-     */
-    private _readStoredBars;
-    series(range?: DateRange): Promise<DailyBar[]>;
-    private _syntheticThresholdSeries;
-    value(date?: string): Promise<number | null>;
-    /**
-     * Read-only preview of the indicator series with an in-memory bar at `date`
-     * computed via `computeAt` with the supplied live-quote `overrides`. Does
-     * NOT write to `indicators_series`. Safe to call before market close.
-     *
-     * @param date - Target trading day whose value is computed in-memory.
-     *   Must be in `tradingDays.getRange()`.
-     * @param overrides - Raw (unleveraged) quotes keyed by market symbol.
-     *   Symbols omitted fall back to the last known value (see `_resolveRawBars`).
-     * @param range - Optional filter applied to the returned bars.
-     * @returns Stored historical bars plus (or with) today's in-memory value.
-     */
-    previewSeries(date: string, overrides: Record<string, number>, range?: DateRange): Promise<DailyBar[]>;
-}
+    /**
+     * Total cost basis of the current quantity in base currency
+     * (fill price × shares + fees at entry, adjusted on partial closes).
+     */
+    basis: number;
+    /** Optional key-value labels for strategy attribution or downstream reporting. */
+    tags?: Record<string, unknown>;
+};
+/**
+ * A point-in-time snapshot of the full portfolio state.
+ *
+ * `t` advances to the latest fill timestamp each time {@link applyFills} is
+ * called. It is used as the portfolio's logical "now" for downstream
+ * computations.
+ *
+ * @example
+ * ```ts
+ * import type { Portfolio } from '@livefolio/sdk';
+ *
+ * const portfolio: Portfolio = {
+ *   cash:      50_000,
+ *   positions: [],
+ *   t:         new Date('2024-01-01'),
+ * };
+ * ```
+ */
+type Portfolio = {
+    /** Uninvested cash in the portfolio's base currency. */
+    cash: number;
+    /** All currently open positions. Immutable array — replaced (not mutated) by apply functions. */
+    positions: ReadonlyArray<Position>;
+    /** Logical timestamp of the most recent fill (or the portfolio's start date). */
+    t: Date;
+};
 
-interface StorageProvider {
-    tickers: {
-        upsert(symbol: string, leverage: number): Promise<{
-            id: number;
-        }>;
-        findOrCreate(symbol: string, leverage: number): Promise<{
-            id: number;
-        }>;
-    };
-    indicators: {
-        upsert(identity: {
-            type: string;
-            tickerId: number | null;
-            lookback: number;
-            delay: number;
-            unit: string | null;
-            threshold: number | null;
-        }): Promise<{
-            id: number;
-        }>;
-        findOrCreate(identity: {
-            type: string;
-            tickerId: number | null;
-            lookback: number;
-            delay: number;
-            unit: string | null;
-            threshold: number | null;
-        }): Promise<{
-            id: number;
-        }>;
-        getSeries(indicatorId: number, range?: DateRange): Promise<DailyBar[]>;
-        writeSeries(indicatorId: number, bars: DailyBar[], opts?: {
-            metadata?: unknown;
-        }): Promise<void>;
-        getLatestSeriesDate(indicatorId: number): Promise<string | null>;
-        getValue(indicatorId: number, date?: string): Promise<number | null>;
-        getLatestBar(indicatorId: number): Promise<{
-            date: string;
-            value: number;
-            metadata: unknown;
-        } | null>;
-    };
-    signals: {
-        upsert(identity: {
-            indicatorId1: number;
-            indicatorId2: number;
-            comparison: string;
-            tolerance: number;
-        }): Promise<{
-            id: number;
-        }>;
-        findOrCreate(identity: {
-            indicatorId1: number;
-            indicatorId2: number;
-            comparison: string;
-            tolerance: number;
-        }): Promise<{
-            id: number;
-        }>;
-        getSeries(signalId: number, range?: DateRange): Promise<DailyBar[]>;
-        writeSeries(signalId: number, bars: DailyBar[]): Promise<void>;
-        getLatestSeriesDate(signalId: number): Promise<string | null>;
-        getLastValue(signalId: number): Promise<number | null>;
-    };
-    allocations: {
-        findOrCreate(holdings: Record<string, number>): Promise<{
-            id: number;
-        }>;
-    };
-    strategies: {
-        create(definition: StrategyDefinition): Promise<{
-            id: number;
-        }>;
-        getSeries(strategyId: number, range?: DateRange): Promise<StrategySeriesEntry[]>;
-        writeSeries(strategyId: number, entries: StrategySeriesEntry[]): Promise<void>;
-        getLatestSeriesDate(strategyId: number): Promise<string | null>;
-        getLatestAllocationId(strategyId: number): Promise<number | null>;
-        resolveReference(linkId: string): Promise<StrategyReferenceData>;
+/**
+ * Opens a new position in `asset`. The executor creates a fresh {@link Position}
+ * entry and debits cash by `quantity * fillPrice + fees`.
+ *
+ * @example
+ * ```ts
+ * import type { OpenOrder } from '@livefolio/sdk';
+ *
+ * const order: OpenOrder = {
+ *   id:       'ord_001',
+ *   kind:     'open',
+ *   asset:    { kind: 'equity', id: 'AAPL', symbol: 'AAPL' },
+ *   side:     'long',
+ *   quantity: 100,
+ *   tag:      'momentum-entry',
+ * };
+ * ```
+ */
+type OpenOrder = {
+    /** Caller-supplied identifier carried back on the resulting {@link Fill} via `orderRef`. */
+    id: string;
+    kind: 'open';
+    /** The instrument to buy (long) or sell short. */
+    asset: Asset;
+    /** `'long'` to buy; `'short'` to sell short. */
+    side: 'long' | 'short';
+    /** Number of shares (or units) to transact. Must be positive. */
+    quantity: number;
+    /** Optional label propagated to the resulting {@link Position} for analysis. */
+    tag?: string;
+};
+/**
+ * Closes an existing position identified by `positionId`. If `quantity` is
+ * supplied, only that many shares are closed (partial close); omitting
+ * `quantity` closes the entire position.
+ *
+ * @example
+ * ```ts
+ * import type { CloseOrder } from '@livefolio/sdk';
+ *
+ * const order: CloseOrder = {
+ *   id:         'ord_002',
+ *   kind:       'close',
+ *   positionId: 'pos_1',
+ * };
+ * ```
+ */
+type CloseOrder = {
+    /** Caller-supplied identifier carried back on the resulting {@link Fill} via `orderRef`. */
+    id: string;
+    kind: 'close';
+    /** ID of the {@link Position} to close. */
+    positionId: PositionId;
+    /**
+     * Shares to close. Omit to close the full position. Must not exceed
+     * the position's current quantity.
+     */
+    quantity?: number;
+};
+/**
+ * Adjusts fields of an existing position without fully closing it. Currently
+ * supports changing `quantity` (e.g. after a corporate action). Cash is not
+ * affected other than deducting fees.
+ *
+ * @example
+ * ```ts
+ * import type { AdjustOrder } from '@livefolio/sdk';
+ *
+ * const order: AdjustOrder = {
+ *   id:         'ord_003',
+ *   kind:       'adjust',
+ *   positionId: 'pos_1',
+ *   changes:    { quantity: 150 },
+ * };
+ * ```
+ */
+type AdjustOrder = {
+    /** Caller-supplied identifier carried back on the resulting {@link Fill} via `orderRef`. */
+    id: string;
+    kind: 'adjust';
+    /** ID of the {@link Position} to modify. */
+    positionId: PositionId;
+    /**
+     * Fields to update. Currently only `quantity` is supported. Omitting a
+     * field leaves it unchanged.
+     */
+    changes: {
+        quantity?: number;
     };
-    tradingDays: {
-        getRange(range?: DateRange): Promise<string[]>;
-        getLatestClosed(): Promise<string | null>;
+};
+/**
+ * Adjusts a long position in `asset` by `delta` shares. Positive `delta`
+ * increases the position (buy); negative `delta` decreases it (sell). If no
+ * position exists and `delta > 0`, a new position is opened.
+ *
+ * Used by the rebalance engine when transitioning a portfolio to target
+ * weights — strategy code typically does not construct these directly.
+ *
+ * @example
+ * ```ts
+ * import type { RebalanceOrder } from '@livefolio/sdk';
+ *
+ * const order: RebalanceOrder = {
+ *   id:    'ord_004',
+ *   kind:  'rebalance',
+ *   asset: { kind: 'equity', id: 'MSFT', symbol: 'MSFT' },
+ *   delta: -50,  // reduce long by 50 shares
+ * };
+ * ```
+ */
+type RebalanceOrder = {
+    /** Caller-supplied identifier carried back on the resulting {@link Fill} via `orderRef`. */
+    id: string;
+    kind: 'rebalance';
+    /** The instrument whose long position is being adjusted. */
+    asset: Asset;
+    /**
+     * Share delta. Positive → buy more; negative → sell (reduce or close).
+     * Zero-delta orders MUST be omitted by callers.
+     */
+    delta: number;
+};
+/**
+ * Discriminated union of all order types. Narrow on `order.kind` to access
+ * kind-specific fields.
+ *
+ * Variants:
+ * - `'open'`      — {@link OpenOrder}: opens a new long or short position.
+ * - `'close'`     — {@link CloseOrder}: closes an existing position fully or partially.
+ * - `'adjust'`    — {@link AdjustOrder}: mutates fields of an existing position.
+ * - `'rebalance'` — {@link RebalanceOrder}: delta-adjusts a long position; used by the
+ *   rebalance engine.
+ *
+ * @example
+ * ```ts
+ * import type { Order } from '@livefolio/sdk';
+ *
+ * function describe(order: Order): string {
+ *   switch (order.kind) {
+ *     case 'open':      return `open ${order.side} ${order.quantity} ${order.asset.symbol}`;
+ *     case 'close':     return `close position ${order.positionId}`;
+ *     case 'adjust':    return `adjust position ${order.positionId}`;
+ *     case 'rebalance': return `rebalance ${order.asset.symbol} by ${order.delta}`;
+ *   }
+ * }
+ * ```
+ */
+type Order = OpenOrder | CloseOrder | AdjustOrder | RebalanceOrder;
+/**
+ * Execution confirmation returned by {@link Executor.submit}. Each fill
+ * corresponds to one order and records the exact price, quantity, and fees
+ * that were transacted.
+ *
+ * @example
+ * ```ts
+ * import type { Fill } from '@livefolio/sdk';
+ *
+ * const fill: Fill = {
+ *   orderRef: 'ord_001',
+ *   t:        new Date('2024-06-04T13:30:00Z'),
+ *   quantity: 100,
+ *   price:    152.75,
+ *   fees:     0.50,
+ * };
+ * ```
+ */
+type Fill = {
+    /** References the `id` of the originating {@link Order}. */
+    orderRef: string;
+    /** Timestamp at which the fill was executed (>= the order submission time). */
+    t: Date;
+    /** Shares (or units) actually transacted. May be less than the ordered quantity for partial fills. */
+    quantity: number;
+    /** Per-share execution price after slippage. */
+    price: number;
+    /** Total transaction fees in the portfolio's base currency. */
+    fees: number;
+};
+
+/**
+ * Constraint on the feature map type parameter used throughout the strategy API.
+ * A `Features` object is a plain, readonly record that maps string keys to arbitrary
+ * computed values. Keeping it generic (rather than forcing `Record<string, number>`)
+ * lets callers attach structured objects, series snapshots, or price maps alongside
+ * numeric scalars.
+ */
+type Features = Readonly<Record<string, unknown>>;
+/**
+ * The contract that every allocation strategy must implement.
+ *
+ * The runtime loop calls these methods in order on every rebalance session:
+ *
+ * 1. `universe` — decide which assets are tradeable today.
+ * 2. `features` — compute any indicators or derived values needed for the decision.
+ * 3. `build` — emit a list of orders (and the next state value) given the feature snapshot.
+ *
+ * Invariants an implementation MUST uphold:
+ * - `universe` must be synchronous and cheap; it is called before any I/O.
+ * - `features` may be async and is responsible for all data fetching and
+ *   indicator computation. The returned `F` value is passed verbatim to `build`.
+ * - `build` must be synchronous. It receives the current portfolio, the
+ *   full feature snapshot, and the carried-over state, and returns zero or more
+ *   orders plus the next state value. Returning an empty array is a valid no-op
+ *   (no rebalance).
+ * - None of the three methods should have side effects on shared mutable state
+ *   between calls; the portfolio is the single source of truth for position state.
+ *
+ * The `F` type parameter lets TypeScript verify that features produced by
+ * `features()` exactly match what `build()` consumes, eliminating a whole class
+ * of runtime key-mismatch bugs.
+ *
+ * The `S` type parameter (defaults to `void`) enables explicit state threading.
+ * When `S = void`, the strategy is state-less: `initialState` is omitted, `build`
+ * receives `undefined` for `state`, and may return either a legacy `ReadonlyArray<Order>`
+ * or the new `{ orders, state: undefined }` form. When `S` is a concrete type,
+ * `initialState()` is required and `build` must return `{ orders, state }` so the
+ * runtime can carry the state forward without closures — enabling snapshot/restore
+ * for preview-builds in live mode.
+ *
+ * @example State-less strategy (legacy shape — S = void):
+ * ```ts
+ * import type { Strategy, Features } from '@livefolio/sdk';
+ *
+ * type MyFeatures = { spy_sma20: number; spy_price: number } & Features;
+ *
+ * const myStrategy: Strategy<MyFeatures> = {
+ *   universe: (_t, _portfolio) => [{ kind: 'equity', id: 'US:SPY', symbol: 'SPY' }],
+ *
+ *   features: async (_universe, _portfolio, _t) => ({
+ *     spy_sma20: 432.5,
+ *     spy_price: 440.0,
+ *   }),
+ *
+ *   build: (features, _portfolio, _state, _t) => {
+ *     if (features.spy_price > features.spy_sma20) {
+ *       // buy signal — delegate actual order creation to reconcile()
+ *     }
+ *     return [];
+ *   },
+ * };
+ * ```
+ *
+ * @example
+ * State-bearing strategy (`S = { lastBar: number }`):
+ * ```ts
+ * import type { Strategy, Features } from '@livefolio/sdk';
+ *
+ * type MyFeatures = { price: number } & Features;
+ * type MyState = { lastBar: number };
+ *
+ * const myStrategy: Strategy<MyFeatures, MyState> = {
+ *   universe: () => [{ kind: 'equity', id: 'US:SPY', symbol: 'SPY' }],
+ *   features: async () => ({ price: 440 }),
+ *   initialState: () => ({ lastBar: 0 }),
+ *   build: (features, _portfolio, state, _t) => ({
+ *     orders: [],
+ *     state: { lastBar: features.price },
+ *   }),
+ * };
+ * ```
+ */
+interface Strategy<F extends Features = Features, S = void> {
+    /**
+     * Returns the set of assets that are eligible for trading on date `t`.
+     *
+     * The universe may change dynamically based on the current portfolio or
+     * calendar date (e.g. exclusion lists, liquidity filters). Assets returned
+     * here are the ones for which `features` will fetch data.
+     *
+     * @param t - The session date (midnight UTC on the trading day).
+     * @param portfolio - The portfolio state carried into this session.
+     * @returns A readonly array of `Asset` descriptors. May be empty if no assets
+     *   are eligible; `build` will then receive no prices and should return `[]`.
+     */
+    universe(t: Date, portfolio: Portfolio): ReadonlyArray<Asset>;
+    /**
+     * Computes the feature snapshot used by `build` to make allocation decisions.
+     *
+     * This is the only async step in the strategy loop. Implementations typically
+     * call `FeatureRuntime.compute` for each indicator, which handles caching and
+     * data fetching transparently.
+     *
+     * @param universe - The assets returned by `universe()` for this session.
+     * @param portfolio - The portfolio state at the start of this session.
+     * @param t - The session date.
+     * @returns A feature object of type `F`, or a promise that resolves to one.
+     *   The object is passed unchanged to `build`.
+     *
+     * @example
+     * ```ts
+     * features: async (universe, _portfolio, t) => {
+     *   const prices = await Promise.all(
+     *     universe.map(async (asset) => {
+     *       const s = await runtime.compute({ kind: 'price' }, asset);
+     *       return [asset.id, seriesAt(s, t)] as const;
+     *     }),
+     *   );
+     *   return { prices: new Map(prices) };
+     * }
+     * ```
+     */
+    features(universe: ReadonlyArray<Asset>, portfolio: Portfolio, t: Date): F | Promise<F>;
+    /**
+     * Returns the initial auxiliary state for this strategy. Optional — when
+     * omitted, the runtime treats the strategy as state-less (`S = void`) and
+     * passes `undefined` for `state` in every `build` call.
+     *
+     * Required for any strategy that holds hysteresis or other carry-over state
+     * across rebalance steps. The returned value MUST be JSON-serializable so the
+     * runtime can snapshot/restore it (preview-build during live mode) and so
+     * `BacktestResult.finalState` round-trips through any persistence layer.
+     */
+    initialState?(): S;
+    /**
+     * Translates the feature snapshot into orders and the next state value.
+     *
+     * Must be synchronous. Returning an empty `orders` array is valid and means
+     * "hold current positions unchanged". Typically delegates weight calculation
+     * to `evaluateRuleTree` and order construction to `reconcile`.
+     *
+     * For state-less strategies (`S = void`), the legacy return shape
+     * `ReadonlyArray<Order>` is still accepted — the runtime normalizes both forms.
+     * New code should always return `{ orders, state }`.
+     *
+     * @param features - The value returned by `features()` for this session.
+     * @param portfolio - The portfolio state at the start of this session.
+     * @param state - The state carried over from the previous session. `undefined`
+     *   when `S = void`.
+     * @param t - The session date.
+     * @returns Either a readonly array of `Order` objects (legacy state-less form)
+     *   or `{ orders: ReadonlyArray<Order>; state: S }` (new state-bearing form).
+     *   The executor receives the orders and converts them into `Fill` records that
+     *   update the portfolio.
+     */
+    build(features: F, portfolio: Portfolio, state: S, t: Date): ReadonlyArray<Order> | {
+        orders: ReadonlyArray<Order>;
+        state: S;
     };
 }
 
-interface SignalIdentity {
-    indicator1: IndicatorHandle;
-    indicator2: IndicatorHandle;
-    comparison: Comparison;
-    tolerance: number;
-}
-declare class SignalHandle {
-    readonly indicator1: IndicatorHandle;
-    readonly indicator2: IndicatorHandle;
-    readonly comparison: Comparison;
-    readonly tolerance: number;
-    private _storage;
-    private _resolvedId;
-    private _resolving;
-    private _cachedSeries;
-    private _cachedAsOf;
-    private _syncing;
-    constructor(storage: StorageProvider, _market: MarketProvider, identity: SignalIdentity);
-    get id(): number;
-    resolve(): Promise<{
-        id: number;
-    }>;
-    static fromResolved(storage: StorageProvider, market: MarketProvider, id: number, identity: SignalIdentity): SignalHandle;
-    private _doResolve;
-    private _getLatestClosedTradingDay;
-    private _getLatestSignalSeriesDate;
-    private _getLastSignalValue;
-    private _ensureFresh;
-    private _isSingleBarFastPath;
-    private _sync;
-    private _evaluateOneBar;
-    private _upsertSeries;
-    private _querySeriesFromDb;
-    /**
-     * Compute the signal's boolean value at `date` without persisting anything,
-     * with optional live-quote `overrides` that are routed through each
-     * indicator's `computeAt`. Returns null if either indicator cannot produce
-     * a value at `date`.
-     *
-     * @param prevBool - The signal's boolean value at the bar immediately
-     *   preceding `date`, used for hysteresis when `tolerance > 0`. If not
-     *   provided, falls back to `storage.signals.getLastValue` (suitable for
-     *   standalone callers). On the preview path `_evaluate` passes this from
-     *   the in-memory `dateMap` so we never read stale storage.
-     */
-    computeAt(date: string, overrides?: Record<string, number>, prevBool?: boolean | null): Promise<boolean | null>;
-    series(range?: DateRange): Promise<DailyBar[]>;
-    value(date?: string): Promise<number | null>;
-    /**
-     * Read-only preview of the signal series with an in-memory bar at `date`
-     * computed via `computeAt` with the supplied live-quote `overrides`. Does
-     * NOT write to `signals_series`.
-     *
-     * @param date - Target trading day whose boolean is computed in-memory.
-     * @param overrides - Raw (unleveraged) quotes keyed by market symbol.
-     * @param range - Optional filter applied to the returned bars.
-     */
-    previewSeries(date: string, overrides: Record<string, number>, range?: DateRange): Promise<DailyBar[]>;
-}
+/**
+ * Maps each asset ID to its desired portfolio weight as a fraction of total
+ * portfolio value (e.g. `0.6` means 60 %). Weights need not sum to 1; any
+ * residual becomes cash. Passing a weight of `0` or omitting an asset entirely
+ * will generate a full exit order for any existing long position in that asset.
+ */
+type TargetWeights = ReadonlyMap<AssetId, number>;
+/**
+ * Maps each asset ID to its current market price. Required for every asset that
+ * appears in `TargetWeights` and for every asset currently held in the portfolio.
+ * `reconcile` throws if a target asset has no corresponding price entry.
+ */
+type PriceMap = ReadonlyMap<AssetId, number>;
+/**
+ * Converts target portfolio weights into a minimal set of `RebalanceOrder`
+ * instructions that move the current portfolio toward the desired allocation.
+ *
+ * The algorithm:
+ * 1. Compute total portfolio value as `cash + Σ(held_shares × price)`.
+ * 2. For each target asset, derive `targetShares = floor(totalValue × weight / price)`.
+ * 3. Emit a `RebalanceOrder` with `delta = targetShares - heldShares` for any
+ *    asset where the delta is non-zero (positive = buy, negative = sell).
+ * 4. Emit exit orders (`delta = -heldShares`) for any long position in an asset
+ *    that does not appear in `targets`.
+ *
+ * Only long positions are considered — short positions in the portfolio are
+ * ignored. Share counts are always floored to integer lots.
+ *
+ * @param targets - Desired weight per asset. Keys are `AssetId` strings. A weight
+ *   of `0` is valid and will result in a full exit for any existing position.
+ * @param portfolio - Current portfolio. Cash and long positions determine total
+ *   value and existing share counts.
+ * @param prices - Current prices for all assets that appear in `targets` or are
+ *   currently held. Throws `Error` if a target asset is missing from this map.
+ * @returns A readonly array of `RebalanceOrder` objects. The array may be empty
+ *   if the portfolio is already at the target allocation. Order IDs are
+ *   deterministic within a single call (`rebal_<assetId>_<counter>`).
+ *
+ * @example
+ * ```ts
+ * import { reconcile } from '@livefolio/sdk';
+ *
+ * const targets = new Map([
+ *   ['US:SPY', 0.6],
+ *   ['US:BND', 0.4],
+ * ]);
+ * const prices = new Map([
+ *   ['US:SPY', 440.0],
+ *   ['US:BND', 75.0],
+ * ]);
+ *
+ * // Empty portfolio with $100 000 cash
+ * const portfolio = { cash: 100_000, positions: [] };
+ * const orders = reconcile(targets, portfolio, prices);
+ * // orders => [
+ * //   { id: 'rebal_US:SPY_0', kind: 'rebalance', asset: { ... }, delta: 136 },
+ * //   { id: 'rebal_US:BND_1', kind: 'rebalance', asset: { ... }, delta: 533 },
+ * // ]
+ * ```
+ */
+declare function reconcile(targets: TargetWeights, portfolio: Portfolio, prices: PriceMap): ReadonlyArray<RebalanceOrder>;
 
-declare class AllocationHandle {
-    readonly holdings: [TickerHandle, number][];
-    private _storage;
-    private _resolvedId;
-    private _resolving;
-    constructor(storage: StorageProvider, holdings: [TickerHandle, number][]);
-    get id(): number;
-    resolve(): Promise<{
-        id: number;
-    }>;
-    static fromResolved(storage: StorageProvider, id: number, holdings: [TickerHandle, number][]): AllocationHandle;
-    toJSON(): Array<{
-        symbol: string;
-        leverage: number;
-        weight: number;
-    }>;
-    private _doResolve;
+/**
+ * A flat record of fundamental data points for an asset at a point in time.
+ * Values may be numeric (e.g. P/E ratio), string (e.g. sector name), or
+ * `null` when a data provider does not carry that field.
+ *
+ * @example
+ * ```ts
+ * import type { Fundamentals } from '@livefolio/sdk';
+ *
+ * const f: Fundamentals = {
+ *   peRatio:    28.5,
+ *   sector:     'Technology',
+ *   debtEquity: null, // not available for this provider
+ * };
+ * ```
+ */
+type Fundamentals = Readonly<Record<string, number | string | null>>;
+/**
+ * Categories of corporate events emitted by {@link DataFeed.events}.
+ *
+ * - `'earnings'`        — quarterly/annual earnings announcement
+ * - `'dividend'`        — cash or stock dividend declaration
+ * - `'split'`           — forward or reverse stock split
+ * - `'corporate-action'`— catch-all for other actions (mergers, spin-offs, etc.)
+ */
+type EventKind = 'earnings' | 'dividend' | 'split' | 'corporate-action';
+/**
+ * A single corporate event affecting an asset.
+ *
+ * The `payload` shape is event-kind-specific and defined by the data provider.
+ * Callers should narrow on `kind` before reading `payload` fields.
+ *
+ * @example
+ * ```ts
+ * import type { DataEvent } from '@livefolio/sdk';
+ *
+ * const event: DataEvent = {
+ *   kind:    'dividend',
+ *   t:       new Date('2024-02-09'),
+ *   asset:   { kind: 'equity', id: 'AAPL', symbol: 'AAPL' },
+ *   payload: { amount: 0.24, currency: 'USD', exDate: '2024-02-09' },
+ * };
+ * ```
+ */
+type DataEvent = {
+    kind: EventKind;
+    /** Effective date of the event (ex-date for dividends, announcement date for earnings). */
+    t: Date;
+    asset: Asset;
+    /** Event-kind-specific fields. Shape is defined by the data provider. */
+    payload: Readonly<Record<string, unknown>>;
+};
+/**
+ * Market-data source. Provides price bars, fundamentals, and corporate events.
+ *
+ * Implementations MUST guarantee:
+ * - `bars` yields {@link Bar} objects in **ascending `t` order**. Gaps (e.g.
+ *   non-trading days) MUST be omitted rather than filled with synthetic bars.
+ * - `bars` respects the half-open interval: the first bar's `t` is `>= range.from`
+ *   and the last bar's `t` is `< range.to`.
+ * - `fundamentals` (optional) returns a snapshot as of `t`; returning `undefined`
+ *   is valid when no data is available.
+ * - `events` (optional) yields events in ascending `t` order, filtered to the
+ *   requested `kinds`.
+ *
+ * Reference implementations: use `vi.fn()` in tests or provide a typed mock
+ * that returns pre-seeded bar arrays.
+ *
+ * @example
+ * ```ts
+ * import type { DataFeed, Asset, DateRange } from '@livefolio/sdk';
+ * import { vi } from 'vitest';
+ *
+ * const feed: DataFeed = {
+ *   bars: vi.fn().mockImplementation(async function* () {
+ *     yield { t: new Date('2024-01-02'), open: 100, high: 102, low: 99, close: 101, volume: 1_000_000 };
+ *   }),
+ * };
+ * ```
+ */
+interface DataFeed {
+    /**
+     * Streams price bars for `asset` over the half-open interval
+     * `[range.from, range.to)` at the requested `freq` granularity.
+     *
+     * Bars MUST be yielded in ascending `t` order. Non-trading periods MUST be
+     * omitted (sparse output is expected and normal).
+     *
+     * @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.
+     * @returns An async iterable of {@link Bar} objects.
+     */
+    bars(asset: Asset, range: DateRange, freq: Frequency): AsyncIterable<Bar>;
+    /**
+     * Returns a snapshot of fundamental data for `asset` as of `t`.
+     * Optional — not all data providers carry fundamentals.
+     *
+     * @param asset - The instrument to query.
+     * @param t     - The point-in-time date for the snapshot.
+     * @returns A flat record of fundamental values, or `undefined` if unavailable.
+     */
+    fundamentals?(asset: Asset, t: Date): Promise<Fundamentals>;
+    /**
+     * Streams corporate events within `range` filtered to the requested
+     * `kinds`. Optional — providers that do not carry event data may omit this.
+     *
+     * Events MUST be yielded in ascending `t` order.
+     *
+     * @param range - Half-open date range.
+     * @param kinds - Event categories to include.
+     * @returns An async iterable of {@link DataEvent} objects.
+     */
+    events?(range: DateRange, kinds: ReadonlyArray<EventKind>): AsyncIterable<DataEvent>;
 }
 
-declare class PortfolioHandle {
-    readonly holdings: [TickerHandle, number][];
-    constructor(holdings: [TickerHandle, number][]);
-    private _priceMap;
-    private _priceFor;
-    value(prices: [TickerHandle, number][]): number;
-    weights(prices: [TickerHandle, number][]): [TickerHandle, number][];
-    trades(target: AllocationHandle, prices: [TickerHandle, number][], date: string): Trade[];
+/**
+ * Order-routing layer. Translates a set of {@link Order} objects into
+ * confirmed {@link Fill} records.
+ *
+ * Implementations MUST guarantee:
+ * - `submit` returns one {@link Fill} per order that was (at least partially)
+ *   executed. Orders that produce zero fills (e.g. quantity of 0) MUST be
+ *   omitted from the result rather than emitting a zero-quantity fill.
+ * - `submit` MUST be **idempotent per unique order id**: submitting the same
+ *   `Order` array twice with the same ids MUST NOT double-fill positions.
+ * - Fill timestamps (`fill.t`) MUST be `>= t`.
+ * - The function is `async`; implementations that need to call a broker API
+ *   or await next-bar price data should resolve only after execution is
+ *   confirmed or simulated.
+ *
+ * Reference implementation: {@link BacktestExecutor} — fills at next-open with
+ * configurable slippage and per-share fees.
+ *
+ * @example
+ * ```ts
+ * import type { Executor, Order, Fill, Portfolio } from '@livefolio/sdk';
+ * import { vi } from 'vitest';
+ *
+ * const executor: Executor = {
+ *   submit: vi.fn().mockResolvedValue([] as ReadonlyArray<Fill>),
+ * };
+ * ```
+ */
+interface Executor {
+    /**
+     * Submits a batch of orders for execution and returns the resulting fills.
+     *
+     * @param orders    - The orders to execute. Each order has a unique `id`;
+     *   implementations use `id` to correlate fills via `fill.orderRef`.
+     * @param t         - The logical "now" timestamp at which orders are being
+     *   submitted (e.g. end-of-day for a daily-rebalance strategy).
+     * @param portfolio - The current portfolio state at time `t`. Implementations
+     *   may use this to resolve position details for close/adjust orders.
+     * @returns A readonly array of {@link Fill} records. One fill per executed
+     *   order; omit orders that result in zero quantity.
+     */
+    submit(orders: ReadonlyArray<Order>, t: Date, portfolio: Portfolio): Promise<ReadonlyArray<Fill>>;
 }
 
-interface MetricsOptions {
-    riskFreeRate?: number;
-    topDrawdowns?: number;
-    varConfidence?: number;
+/**
+ * Wall-clock time of day, expressed in local exchange time.
+ *
+ * @example
+ * ```ts
+ * import type { TimeOfDay } from '@livefolio/sdk';
+ *
+ * const marketOpen: TimeOfDay = { h: 9, m: 30 };  // 09:30 NYSE
+ * const earlyClose: TimeOfDay = { h: 13, m: 0 };  // 13:00 on early-close days
+ * ```
+ */
+type TimeOfDay = {
+    h: number;
+    m: number;
+};
+/**
+ * The open and close instants for a single trading session.
+ *
+ * `date` is midnight of the session day (used as a stable key).
+ * `open` and `close` are the exact UTC instants the exchange accepts orders.
+ *
+ * @example
+ * ```ts
+ * import type { Session } from '@livefolio/sdk';
+ *
+ * // A normal NYSE session
+ * const session: Session = {
+ *   date:  new Date('2024-06-03'),
+ *   open:  new Date('2024-06-03T13:30:00Z'), // 09:30 ET in UTC
+ *   close: new Date('2024-06-03T20:00:00Z'), // 16:00 ET in UTC
+ * };
+ * ```
+ */
+type Session = {
+    date: Date;
+    open: Date;
+    close: Date;
+};
+/**
+ * Exchange calendar — the single source of truth for trading-day arithmetic.
+ *
+ * Implementations MUST guarantee:
+ * - `isOpen(t)` returns `true` only for instants strictly within a session
+ *   `[session.open, session.close)`.
+ * - `next(t)` returns the midnight-UTC Date of the **next** trading day after
+ *   `t`; it MUST never return a weekend or holiday.
+ * - `previous(t)` is the symmetric inverse of `next`.
+ * - `sessions(range)` returns one Date per trading day in the half-open
+ *   interval `[range.from, range.to)`, in ascending order.
+ * - `schedule(range)` returns the same dates as `sessions` but enriched with
+ *   `open`/`close` instants for each session.
+ * - `isEarlyClose(t)` returns `true` if the session containing (or nearest to)
+ *   `t` ends before the exchange's normal close time.
+ *
+ * Reference implementation: {@link NYSEExchangeCalendar}, {@link LSEExchangeCalendar}.
+ *
+ * @example
+ * ```ts
+ * import { NYSEExchangeCalendar } from '@livefolio/sdk';
+ *
+ * const cal = new NYSEExchangeCalendar();
+ * const today = new Date('2024-11-29'); // Black Friday (early close)
+ * console.log(cal.isEarlyClose(today)); // true
+ * const next = cal.next(today);
+ * console.log(next.toISOString());      // 2024-12-02T00:00:00.000Z
+ * ```
+ */
+interface Calendar {
+    /**
+     * Returns `true` if `t` falls inside an open trading session for this
+     * exchange (i.e. between session open and session close, inclusive of open,
+     * exclusive of close).
+     *
+     * @param t - The instant to test.
+     */
+    isOpen(t: Date): boolean;
+    /**
+     * Returns the midnight-UTC Date of the next trading day strictly after `t`.
+     * Skips weekends, exchange holidays, and any days with no scheduled session.
+     *
+     * @param t - Reference date. If `t` itself is a trading day the result is
+     *   the *following* trading day, not `t`.
+     */
+    next(t: Date): Date;
+    /**
+     * Returns the midnight-UTC Date of the most recent trading day strictly
+     * before `t`. Symmetric inverse of {@link Calendar.next}.
+     *
+     * @param t - Reference date.
+     */
+    previous(t: Date): Date;
+    /**
+     * Returns the trading days (as midnight-UTC Dates) within the half-open
+     * interval `[range.from, range.to)`, in ascending order.
+     *
+     * @param range - Half-open date range; `range.from` is inclusive, `range.to`
+     *   is exclusive.
+     * @returns Ascending array of trading-day Dates. Empty if no trading days
+     *   fall in the range.
+     *
+     * @example
+     * ```ts
+     * import { NYSEExchangeCalendar } from '@livefolio/sdk';
+     *
+     * const cal = new NYSEExchangeCalendar();
+     * const days = cal.sessions({
+     *   from: new Date('2024-12-23'),
+     *   to:   new Date('2025-01-02'),
+     * });
+     * // days.length === 5 (skips Christmas, Boxing Day is US-only partial, New Year's)
+     * ```
+     */
+    sessions(range: DateRange): ReadonlyArray<Date>;
+    /**
+     * Returns full {@link Session} records (date, open instant, close instant)
+     * for every trading day in the half-open interval `[range.from, range.to)`.
+     *
+     * @param range - Half-open date range.
+     * @returns Ascending array of {@link Session} objects. Early-close days have
+     *   a `close` earlier than the normal session close.
+     */
+    schedule(range: DateRange): ReadonlyArray<Session>;
+    /**
+     * Returns `true` if the exchange closes early on the day containing `t`.
+     * Common examples: Black Friday (US), Christmas Eve, New Year's Eve.
+     *
+     * @param t - The instant or day to test.
+     */
+    isEarlyClose(t: Date): boolean;
 }
-interface DrawdownEntry {
-    peakDate: string;
-    troughDate: string;
-    recoveryDate: string | null;
-    depth: number;
-    durationDays: number;
-    underwaterDays: number;
+
+/**
+ * Identifies what an indicator was computed over — either a single asset or
+ * a whole universe.
+ *
+ * - `{ kind: 'asset'; asset: AssetId }` — the indicator was computed for a
+ *   specific instrument (e.g. 20-day SMA for AAPL).
+ * - `{ kind: 'universe'; universeHash: string }` — the indicator covers the
+ *   full universe (e.g. cross-sectional momentum rank). `universeHash` is a
+ *   content-hash of the sorted asset-id list so that cache keys survive
+ *   universe reordering.
+ */
+type FeatureScope = {
+    kind: 'asset';
+    asset: AssetId;
+} | {
+    kind: 'universe';
+    universeHash: string;
+};
+/**
+ * Content-addressed cache key for a feature computation result.
+ *
+ * Every field participates in key equality — changing any one of them
+ * addresses a different cache entry. Use this type when building custom
+ * {@link FeatureCache} implementations.
+ *
+ * @example
+ * ```ts
+ * import type { FeatureKey } from '@livefolio/sdk';
+ *
+ * const key: FeatureKey = {
+ *   feature:    'sma',
+ *   paramsHash: 'abc123',           // hash of { window: 20 }
+ *   scope:      { kind: 'asset', asset: 'AAPL' },
+ *   range:      { from: new Date('2024-01-01'), to: new Date('2025-01-01') },
+ *   freq:       '1d',
+ * };
+ * ```
+ */
+type FeatureKey = {
+    /** Feature name, e.g. `'sma'`, `'rsi'`. */
+    feature: string;
+    /** Deterministic hash of the feature's parameter object. */
+    paramsHash: string;
+    /** Asset or universe this result covers. */
+    scope: FeatureScope;
+    /** The date range the cached series spans. */
+    range: DateRange;
+    /** Bar granularity used when computing the feature. */
+    freq: Frequency;
+};
+/**
+ * Content-addressed cache for feature computation results.
+ *
+ * Implementations MUST guarantee:
+ * - `get` returns the exact `Series` previously stored under `key`, or
+ *   `undefined` if no entry exists. It MUST NOT return a stale or partially
+ *   overlapping series.
+ * - `set` stores `series` under `key` and makes it immediately available to
+ *   subsequent `get` calls.
+ * - `invalidate` (optional) removes all entries whose key fields match the
+ *   supplied `prefix`. Partial matches (specifying only `feature`, for example)
+ *   MUST invalidate every key that shares those fields, regardless of the
+ *   remaining fields.
+ * - All methods are `async`; implementations backed by in-process Maps may
+ *   resolve synchronously via `Promise.resolve`.
+ *
+ * Reference implementation: {@link MemoryFeatureCache} — in-process Map,
+ * no eviction, suitable for single-run backtests.
+ *
+ * @example
+ * ```ts
+ * import { MemoryFeatureCache } from '@livefolio/sdk';
+ * import type { FeatureKey, Series } from '@livefolio/sdk';
+ *
+ * const cache = new MemoryFeatureCache();
+ * const key: FeatureKey = {
+ *   feature:    'sma',
+ *   paramsHash: 'abc123',
+ *   scope:      { kind: 'asset', asset: 'AAPL' },
+ *   range:      { from: new Date('2024-01-01'), to: new Date('2025-01-01') },
+ *   freq:       '1d',
+ * };
+ * const series: Series = [{ t: new Date('2024-01-02'), v: 150.5 }];
+ *
+ * await cache.set(key, series);
+ * const hit = await cache.get(key); // same reference
+ * ```
+ */
+interface FeatureCache {
+    /**
+     * Retrieves the cached {@link Series} for `key`, or `undefined` on a cache
+     * miss.
+     *
+     * @param key - Fully-qualified cache key.
+     * @returns The stored series, or `undefined` if not present.
+     */
+    get(key: FeatureKey): Promise<Series | undefined>;
+    /**
+     * Stores `series` under `key`. Overwrites any existing entry at that key.
+     *
+     * @param key    - Fully-qualified cache key.
+     * @param series - The computed series to store. Must not be mutated after
+     *   passing to `set`.
+     */
+    set(key: FeatureKey, series: Series): Promise<void>;
+    /**
+     * Removes all cache entries whose keys match the supplied `prefix`.
+     * Optional — implementations that do not support invalidation may omit this.
+     *
+     * Matching is field-by-field: only the fields present in `prefix` are
+     * compared; all others are treated as wildcards.
+     *
+     * @param prefix - Partial {@link FeatureKey}. Omitted fields match any value.
+     */
+    invalidate?(prefix: Partial<FeatureKey>): Promise<void>;
 }
-interface MonthlyReturnsTable {
-    rows: Array<{
-        year: number;
-        months: (number | null)[];
-        ytd: number | null;
-    }>;
+
+/**
+ * The OHLCV field of a `Bar` that should be used when converting a bar array
+ * into a scalar time series. Defaults to `'close'` throughout the feature
+ * pipeline unless overridden via `FeatureRuntimeOptions.field`.
+ *
+ * Variants: `'open'` | `'high'` | `'low'` | `'close'` | `'volume'`.
+ */
+type BarField = 'open' | 'high' | 'low' | 'close' | 'volume';
+/**
+ * Drains an `AsyncIterable<Bar>` into a plain `Bar[]` array.
+ *
+ * Used internally by `FeatureRuntime` to materialise the stream returned by
+ * `DataFeed.bars` before passing it to indicator functions that expect a
+ * fully-in-memory array. The resulting array is in the same order as the
+ * iterable yields (typically chronological).
+ *
+ * @param it - Any `AsyncIterable<Bar>`, such as the return value of `DataFeed.bars`.
+ * @returns A promise that resolves to a `Bar[]` containing every bar yielded
+ *   by the iterable, in iteration order.
+ *
+ * @example
+ * ```ts
+ * import { collectBars } from '@livefolio/sdk';
+ *
+ * const bars = await collectBars(dataFeed.bars(asset, range, '1d'));
+ * // bars is now a Bar[] — safe to index, slice, and pass to barsToSeries
+ * ```
+ */
+declare function collectBars(it: AsyncIterable<Bar>): Promise<Bar[]>;
+/**
+ * Converts an array of OHLCV bars into a `Series` by extracting a single
+ * numeric field from each bar.
+ *
+ * The resulting `Series` is a readonly array of `{ t: Date; v: number }` points
+ * in the same order as `bars`. The timestamp `t` is taken directly from `bar.t`,
+ * and `v` is the value of `field` for that bar.
+ *
+ * @param bars - Source OHLCV bars in chronological order.
+ * @param field - Which OHLCV field to extract. Defaults to `'close'`.
+ * @returns A `Series` of the same length as `bars`. Returns an empty array when
+ *   `bars` is empty.
+ *
+ * @example
+ * ```ts
+ * import { collectBars, barsToSeries } from '@livefolio/sdk';
+ *
+ * const bars = await collectBars(dataFeed.bars(asset, range, '1d'));
+ * const closeSeries = barsToSeries(bars);           // default: 'close'
+ * const volumeSeries = barsToSeries(bars, 'volume');
+ * ```
+ */
+declare function barsToSeries(bars: ReadonlyArray<Bar>, field?: BarField): Series;
+/**
+ * Looks up the value at or immediately before timestamp `t` in a sorted `Series`.
+ *
+ * Uses binary search to find the largest index `i` where `series[i].t <= t`.
+ * This is the standard "as-of" lookup used throughout the strategy loop to read
+ * the most recent indicator value available on a given session date without
+ * peeking into the future.
+ *
+ * @param series - A `Series` sorted in ascending timestamp order. Behaviour is
+ *   undefined for unsorted input.
+ * @param t - The target date. May fall between two data points or exactly on one.
+ * @returns The `v` value of the last data point at or before `t`, or `undefined`
+ *   if the series is empty or every point comes after `t`.
+ *
+ * @example
+ * ```ts
+ * import { seriesAt } from '@livefolio/sdk';
+ *
+ * const series = [
+ *   { t: new Date('2023-01-02'), v: 380.0 },
+ *   { t: new Date('2023-01-03'), v: 385.0 },
+ *   { t: new Date('2023-01-04'), v: 390.0 },
+ * ];
+ *
+ * seriesAt(series, new Date('2023-01-03')); // => 385.0 (exact match)
+ * seriesAt(series, new Date('2023-01-03T12:00:00Z')); // => 385.0 (between points)
+ * seriesAt(series, new Date('2023-01-01')); // => undefined (before all points)
+ * ```
+ */
+declare function seriesAt(series: Series, t: Date): number | undefined;
+
+/**
+ * Controls whether `returnSeries` computes percentage or absolute returns.
+ *
+ * - `'pct'` (default) — percentage return: `(curr - prev) / prev`. The result is
+ *   a dimensionless ratio (e.g. `0.05` means +5 %).
+ * - `'abs'` — absolute price difference: `curr - prev`. The result is in the same
+ *   units as the input price series.
+ */
+type ReturnMode = 'pct' | 'abs';
+/**
+ * Computes a rolling period return over a price series.
+ *
+ * Math definition:
+ * ```
+ * // Percentage (default):
+ * return[i] = (series[i] - series[i - period]) / series[i - period]
+ *
+ * // Absolute:
+ * return[i] = series[i] - series[i - period]
+ * ```
+ *
+ * Warmup: the first `period` bars are consumed as the lookback window for the
+ * first output. The first output point corresponds to input index `period`.
+ * The output array is shorter than the input (no `undefined` placeholders).
+ *
+ * Edge cases:
+ * - `period <= 0` — throws `Error`.
+ * - `series.length <= period` — returns `[]` (needs strictly more than `period` bars).
+ * - `mode === 'pct'` with `prev === 0` — produces `Infinity` or `NaN`; callers
+ *   should filter or guard against zero-price series.
+ *
+ * @param series - Input price series sorted in ascending timestamp order.
+ * @param period - Lookback distance in bars. A value of `1` gives a single-bar
+ *   (daily) return; larger values give multi-bar returns.
+ * @param mode - Whether to return a percentage ratio or an absolute difference.
+ *   Defaults to `'pct'`.
+ * @returns A `Series` of length `max(0, series.length - period)`. Each point's
+ *   timestamp `t` is taken from `series[i]` (the later of the two bars).
+ *
+ * @example
+ * ```ts
+ * import { returnSeries } from '@livefolio/sdk';
+ *
+ * const prices = [
+ *   { t: new Date('2023-01-02'), v: 100 },
+ *   { t: new Date('2023-01-03'), v: 105 },
+ *   { t: new Date('2023-01-04'), v: 110 },
+ * ];
+ *
+ * const pct = returnSeries(prices, 1);
+ * // pct[0] => { t: new Date('2023-01-03'), v: 0.05 }  // (105-100)/100
+ * // pct[1] => { t: new Date('2023-01-04'), v: ~0.048 } // (110-105)/105
+ *
+ * const abs = returnSeries(prices, 1, 'abs');
+ * // abs[0] => { t: new Date('2023-01-03'), v: 5 }  // 105-100
+ * // abs[1] => { t: new Date('2023-01-04'), v: 5 }  // 110-105
+ *
+ * // Two-bar return
+ * const twoBar = returnSeries(prices, 2);
+ * // twoBar[0] => { t: new Date('2023-01-04'), v: 0.1 } // (110-100)/100
+ * ```
+ */
+declare function returnSeries(series: Series, period: number, mode?: ReturnMode): Series;
+
+/**
+ * A discriminated union describing every built-in feature kind and its parameters.
+ *
+ * Each variant has a `kind` field that identifies the indicator together with the
+ * parameters that fully determine its output. `FeatureSpec` objects are used as
+ * cache keys (via `paramsHash`) and as dispatch tokens (via `getFeatureCompute`).
+ *
+ * Variants:
+ * - `{ kind: 'price' }` — raw price series; no parameters.
+ * - `{ kind: 'sma'; period: number }` — simple moving average over `period` bars.
+ * - `{ kind: 'ema'; period: number }` — exponential moving average seeded from an SMA.
+ * - `{ kind: 'rsi'; period: number }` — Wilder's Relative Strength Index.
+ * - `{ kind: 'return'; period: number; mode?: ReturnMode }` — period return; percent or absolute.
+ * - `{ kind: 'volatility'; period: number }` — rolling population standard deviation of daily returns.
+ * - `{ kind: 'drawdown'; period: number }` — drawdown relative to the rolling maximum.
+ */
+type FeatureSpec = {
+    kind: 'price';
+} | {
+    kind: 'sma';
+    period: number;
+} | {
+    kind: 'ema';
+    period: number;
+} | {
+    kind: 'rsi';
+    period: number;
+} | {
+    kind: 'return';
+    period: number;
+    mode?: ReturnMode;
+} | {
+    kind: 'volatility';
+    period: number;
+} | {
+    kind: 'drawdown';
+    period: number;
+};
+/**
+ * String literal union of all valid feature `kind` values derived from `FeatureSpec`.
+ *
+ * Useful for typing registry keys and dispatch tables without manually listing all
+ * variants: `'price' | 'sma' | 'ema' | 'rsi' | 'return' | 'volatility' | 'drawdown'`.
+ */
+type FeatureKind = FeatureSpec['kind'];
+/**
+ * A pure function that computes a feature `Series` from an input price `Series` and the typed
+ * `FeatureSpec` describing the indicator's parameters. Implementations must be deterministic and
+ * side-effect free — the SDK uses the function as a content-addressed dispatch token via
+ * {@link getFeatureCompute} and as the registration target for {@link defineFeature}.
+ *
+ * @param series - Input price series (typically the asset's close prices).
+ * @param spec   - Typed indicator spec carrying the parameters relevant to `kind`.
+ * @returns The computed feature series, aligned to `series` on `t`.
+ */
+type ComputeFn = (series: Series, spec: FeatureSpec) => Series;
+/**
+ * Registers a compute function for a new or existing feature kind.
+ *
+ * Throws if `kind` is already registered. Call this once at module initialisation
+ * time (top-level) to extend the built-in feature registry with custom indicators.
+ * The compute function receives the raw price `Series` and the full typed spec
+ * object for that kind; it must return a `Series` of the same or shorter length.
+ *
+ * @param kind - The `FeatureKind` string that identifies this indicator.
+ * @param compute - Pure function that transforms a price series according to `spec`.
+ *   The `spec` argument is narrowed to `Extract<FeatureSpec, { kind: K }>` so
+ *   TypeScript enforces that only the correct parameter shape is accessed.
+ * @returns `void`. Registration is a side-effectful, one-time operation.
+ *
+ * @example
+ * ```ts
+ * import { defineFeature } from '@livefolio/sdk';
+ *
+ * // Register a custom 'zscore' feature kind
+ * defineFeature('sma', (series, spec) => {
+ *   // Already built-in; this would throw due to duplicate registration.
+ *   // Shown here for illustration only.
+ *   return series;
+ * });
+ * ```
+ */
+declare function defineFeature<K extends FeatureKind>(kind: K, compute: (series: Series, spec: Extract<FeatureSpec, {
+    kind: K;
+}>) => Series): void;
+/**
+ * Retrieves the registered compute function for a given feature kind.
+ *
+ * Throws `Error` if the kind has not been registered. In normal usage the
+ * built-in `defineFeature` calls at the bottom of this module pre-populate the
+ * registry, so this function only throws for custom kinds that were never registered.
+ *
+ * @param kind - The `FeatureKind` string to look up.
+ * @returns The `ComputeFn` registered for `kind`.
+ *
+ * @example
+ * ```ts
+ * import { getFeatureCompute } from '@livefolio/sdk';
+ *
+ * const computeSma = getFeatureCompute('sma');
+ * const result = computeSma(priceSeries, { kind: 'sma', period: 20 });
+ * ```
+ */
+declare function getFeatureCompute(kind: FeatureKind): ComputeFn;
+/**
+ * Returns a deterministic string that depends only on the spec's logical
+ * content — key order and undefined optional fields are normalized away.
+ *
+ * The same logical spec always produces the same hash regardless of how the
+ * object was constructed (different key insertion order, explicit `undefined`
+ * vs. omitted optional field). This string is used as the `paramsHash` field
+ * in `FeatureKey` to ensure cache-hit equivalence for semantically identical
+ * specs.
+ *
+ * Callers depend on this function's contract (same logical content → same
+ * result), not on the encoding. Future replacement with SHA-256 is
+ * non-breaking.
+ *
+ * @param spec - The `FeatureSpec` object to hash.
+ * @returns A JSON string with sorted keys and no undefined values.
+ *
+ * @example
+ * ```ts
+ * import { paramsHash } from '@livefolio/sdk';
+ *
+ * paramsHash({ kind: 'sma', period: 20 });
+ * // => '{"kind":"sma","period":20}'
+ *
+ * // Optional field omitted vs explicitly undefined — same result:
+ * paramsHash({ kind: 'return', period: 10 });
+ * paramsHash({ kind: 'return', period: 10, mode: undefined });
+ * // both => '{"kind":"return","period":10}'
+ * ```
+ */
+declare function paramsHash(spec: FeatureSpec): string;
+
+/**
+ * Configuration for a `FeatureRuntime` instance.
+ *
+ * Accepts two shapes — select via the `mode` discriminant:
+ *
+ * - **`'historical'`** (default, `mode` may be omitted): range-bounded backtest
+ *   mode. Bars are fetched from `DataFeed` once per asset and cached in memory.
+ * - **`'streaming'`**: open-ended live mode. No fixed `range`; bars are pushed
+ *   in via `appendBar`. Indicator computation reads from the growing in-process
+ *   buffer instead of calling `DataFeed.bars`.
+ *
+ * The historical variant is backward-compatible — existing callers that omit
+ * `mode` compile and behave identically to before.
+ */
+type FeatureRuntimeOptions = {
+    /** Selects historical (range-bounded) mode. May be omitted; defaults to
+     *  `'historical'`. */
+    mode?: 'historical';
+    /** The market-data source used to fetch OHLCV bars. */
+    dataFeed: DataFeed;
+    /**
+     * Persistent indicator cache. Use `MemoryFeatureCache` for a single backtest
+     * run, or supply a cross-process cache implementation to share results across
+     * multiple runs or processes.
+     */
+    featureCache: FeatureCache;
+    /**
+     * The date range over which bars are fetched. This should span at least the
+     * backtest range plus any indicator warmup period (e.g. `period - 1` extra
+     * bars for SMA/EMA). `FeatureRuntime` does not automatically extend the range
+     * for warmup — the caller is responsible for providing enough history.
+     */
+    range: DateRange;
+    /**
+     * Bar frequency forwarded to `DataFeed.bars` and embedded in cache keys.
+     * Must match the granularity expected by the indicators (e.g. `'1d'` for
+     * daily SMA/EMA).
+     */
+    freq: Frequency;
+    /**
+     * Which OHLCV field to use as the scalar price series. Defaults to `'close'`.
+     * All indicators within a single `FeatureRuntime` instance share the same field.
+     */
+    field?: BarField;
+} | {
+    /** Selects streaming (open-ended live) mode. Required. */
+    mode: 'streaming';
+    /** Optional — not called in streaming mode. Omit in streaming-only usages.
+     *  If provided it is stored but never invoked; supply only when sharing an
+     *  options object that also carries a `DataFeed` for other purposes. */
+    dataFeed?: DataFeed;
+    /**
+     * Persistent indicator cache. In streaming mode the cache is bypassed
+     * entirely — every `compute` call recomputes from the in-memory bar buffer.
+     * The instance is still required so that a shared cache object can be
+     * passed without special-casing at the call site.
+     */
+    featureCache: FeatureCache;
+    /**
+     * Bar frequency embedded in cache keys. Must match the granularity of the
+     * bars pushed via `appendBar`.
+     */
+    freq: Frequency;
+    /**
+     * Which OHLCV field to use as the scalar price series. Defaults to `'close'`.
+     */
+    field?: BarField;
+    /**
+     * Optional seed bars per asset (keyed by `AssetId`), used to bootstrap the
+     * streaming buffer from a prior historical run's `BacktestResult`.
+     * Bars must already be in ascending `t` order per asset.
+     */
+    initialBars?: ReadonlyMap<AssetId, ReadonlyArray<Bar>>;
+};
+/**
+ * Orchestrates indicator computation for a single backtest run or a live
+ * streaming session.
+ *
+ * `FeatureRuntime` is the bridge between raw OHLCV data (via `DataFeed`) and the
+ * typed indicator functions registered in the feature registry. It handles:
+ *
+ * - **Bar fetching** (historical mode) — Calls `DataFeed.bars` once per
+ *   `(asset, range, freq)` tuple and caches the resulting `Series` in memory for
+ *   the lifetime of the instance. Concurrent calls for the same asset share a
+ *   single in-flight promise; there is no redundant fetching even if `compute` is
+ *   called from multiple `Promise.all` branches simultaneously.
+ * - **Bar buffering** (streaming mode) — Bars are pushed in via `appendBar`.
+ *   `compute` reads directly from the in-memory buffer; `DataFeed.bars` is never
+ *   called.
+ * - **Indicator dispatch** — Delegates computation to the function registered via
+ *   `defineFeature` for the given `FeatureSpec.kind`.
+ * - **Persistent caching** (historical mode only) — Checks `FeatureCache` before
+ *   computing. On a miss, the result is stored in the cache. Subsequent calls with
+ *   the same `(spec, asset)` combination return instantly from cache without
+ *   re-fetching bars.
+ *
+ * Caching semantics:
+ * - Historical mode: cache keys incorporate `spec`, `asset.id`, `range`, and `freq`.
+ *   Results are read from and written to `featureCache`.
+ * - Streaming mode: `featureCache` is bypassed entirely — every `compute` call
+ *   recomputes from the growing in-memory bar buffer. The `seriesCache` (per-asset
+ *   in-memory base-series cache) is the only cache layer; it is invalidated on each
+ *   `appendBar` so the next `compute` sees the updated buffer.
+ * - Calling `appendBar` invalidates the in-memory series cache for that asset so
+ *   the next `compute` call rebuilds the series from the updated buffer.
+ *
+ * @example Historical mode (default)
+ * ```ts
+ * import {
+ *   FeatureRuntime,
+ *   MemoryFeatureCache,
+ *   seriesAt,
+ * } from '@livefolio/sdk';
+ *
+ * const runtime = new FeatureRuntime({
+ *   dataFeed,
+ *   featureCache: new MemoryFeatureCache(),
+ *   range: { from: new Date('2022-01-01'), to: new Date('2023-12-31') },
+ *   freq: '1d',
+ * });
+ *
+ * const spy = { kind: 'equity' as const, id: 'US:SPY', symbol: 'SPY' };
+ * const smaSeries = await runtime.compute({ kind: 'sma', period: 20 }, spy);
+ * const latestSma = seriesAt(smaSeries, new Date('2023-06-15'));
+ * // => number | undefined
+ * ```
+ *
+ * @example Streaming mode
+ * ```ts
+ * const runtime = new FeatureRuntime({
+ *   featureCache: new MemoryFeatureCache(),
+ *   mode: 'streaming',
+ *   freq: '1d',
+ *   initialBars,         // optional seed from BacktestResult
+ * });
+ *
+ * runtime.appendBar(spy, latestBar);
+ * const smaSeries = await runtime.compute({ kind: 'sma', period: 20 }, spy);
+ * ```
+ */
+declare class FeatureRuntime {
+    private readonly mode;
+    private readonly dataFeed;
+    private readonly featureCache;
+    private readonly range;
+    private readonly freq;
+    private readonly field;
+    /** Per-asset bar buffer used in streaming mode. */
+    private readonly streamingBars;
+    /** Per-asset bar buffer accumulated in historical mode after bars are fetched from DataFeed. */
+    private readonly historicalBars;
+    /** Per-asset in-flight Series promise — shared across concurrent `compute` calls
+     *  for the same asset to avoid redundant bar fetching (historical) or rebuilding
+     *  (streaming). Invalidated on `appendBar`. */
+    private readonly seriesCache;
+    constructor(opts: FeatureRuntimeOptions);
+    /**
+     * Appends a bar to the streaming buffer for the given asset.
+     *
+     * Bars must be provided in non-decreasing `t` order per asset. A bar with
+     * the same `t` as the most recent buffered bar replaces it in place — this
+     * is the mark-to-market wiggle path used by `runLive`, where each incoming
+     * tick updates the running open/high/low/close of the in-flight session bar.
+     * A bar with `t` strictly greater than the buffered tail starts a fresh
+     * in-flight bar (e.g. at session boundaries). A bar with `t` strictly less
+     * than the buffered tail throws.
+     *
+     * Also invalidates the in-memory series cache for the asset so the next
+     * `compute` call rebuilds the series from the updated buffer.
+     *
+     * @throws If called on a historical-mode runtime.
+     * @throws If `bar.t` is strictly less than the last buffered bar's `t`.
+     */
+    appendBar(asset: Asset, bar: Bar): void;
+    private baseSeries;
+    /**
+     * Returns the bar buffer for `asset`, or an empty array if none has been
+     * fetched/buffered yet.
+     *
+     * In historical mode this is populated after the first `compute` call that
+     * triggers a bar fetch for the asset. In streaming mode it reflects all bars
+     * pushed via `appendBar`.
+     */
+    getBars(asset: Asset): ReadonlyArray<Bar>;
+    /**
+     * Returns the full per-asset bar map (keyed by `AssetId`). Merges historical
+     * and streaming buffers (streaming wins on collision, but in practice an
+     * instance is in one mode at a time so collisions don't occur).
+     *
+     * Returns a fresh `Map` — callers cannot mutate the internal state.
+     */
+    getAllBars(): ReadonlyMap<AssetId, ReadonlyArray<Bar>>;
+    private cacheKey;
+    /**
+     * Computes (or retrieves from cache) the output `Series` for a given feature
+     * spec applied to a specific asset.
+     *
+     * **Historical mode:** on the first call for a `(spec, asset)` pair:
+     * 1. Fetches or reuses the in-memory base `Series` for the asset.
+     * 2. Dispatches to the registered compute function for `spec.kind`.
+     * 3. Stores the result in `featureCache`.
+     * On subsequent calls, returns the cached `Series` directly from `featureCache`.
+     *
+     * **Streaming mode:** reads from the in-memory bar buffer populated via
+     * `appendBar`. `DataFeed.bars` is never called. The persistent `featureCache`
+     * is bypassed entirely — results are never read from or written to it.
+     * The in-memory `seriesCache` (base series per asset) is the only cache layer
+     * and is invalidated on each `appendBar`, so every `compute` after a new bar
+     * reflects the updated buffer.
+     *
+     * @param spec - The feature specification describing which indicator to compute
+     *   and its parameters (e.g. `{ kind: 'sma', period: 20 }`).
+     * @param asset - The asset for which to compute the feature. The asset's `id`
+     *   is used both for data fetching and cache key construction.
+     * @returns A promise that resolves to the computed `Series`. The series length
+     *   is determined by the indicator's warmup: for example, SMA(20) returns
+     *   `series.length - 19` data points. Returns an empty array when the
+     *   base series is shorter than the indicator's warmup period.
+     *
+     * @example
+     * ```ts
+     * const spy = { kind: 'equity' as const, id: 'US:SPY', symbol: 'SPY' };
+     *
+     * const [priceSeries, smaSeries] = await Promise.all([
+     *   runtime.compute({ kind: 'price' }, spy),
+     *   runtime.compute({ kind: 'sma', period: 20 }, spy),
+     * ]);
+     * ```
+     */
+    compute(spec: FeatureSpec, asset: Asset): Promise<Series>;
 }
-interface MetricsResult {
-    range: {
-        from: string;
-        to: string;
-        years: number;
-    };
-    returns: {
-        totalReturn: number;
-        cagr: number;
-        bestYear: {
-            year: number;
-            return: number;
-        } | null;
-        worstYear: {
-            year: number;
-            return: number;
-        } | null;
-        bestMonth: {
-            date: string;
-            return: number;
-        } | null;
-        worstMonth: {
-            date: string;
-            return: number;
-        } | null;
-        pctPositiveMonths: number;
-    };
-    risk: {
-        volatility: number;
-        downsideDeviation: number;
-        maxDrawdown: DrawdownEntry;
-        currentDrawdown: number;
-        ulcerIndex: number;
-        skew: number;
-        kurtosis: number;
-        var95: number;
-        cvar95: number;
-    };
-    riskAdjusted: {
-        sharpe: number;
-        sortino: number;
-        calmar: number;
-    };
-    activity: {
-        rebalances: number;
-        trades: number;
-        turnover: number;
-        winRate: number;
-    };
-    tables: {
-        drawdowns: DrawdownEntry[];
-        monthly: MonthlyReturnsTable;
-        yearly: Array<{
-            year: number;
-            return: number;
-        }>;
-    };
+
+/**
+ * All inputs required to run a historical backtest.
+ *
+ * Callers must provide a concrete `Strategy`, a `DateRange`, and the four
+ * pluggable runtime layers (`dataFeed`, `executor`, `calendar`, `featureCache`).
+ * The reference implementations (`MemoryFeatureCache`, `BacktestExecutor`,
+ * `NYSEExchangeCalendar`) satisfy all four without network dependencies.
+ */
+type RunBacktestOptions<F extends Features = Features, S = unknown> = {
+    /** The strategy under test. Must implement `universe`, `features`, and `build`. */
+    strategy: Strategy<F, S>;
+    /**
+     * Inclusive date range over which to iterate. The calendar resolves this
+     * range into the actual sequence of trading sessions.
+     */
+    range: DateRange;
+    /**
+     * Starting portfolio state. Cash and positions are carried forward through
+     * the simulation as orders are filled. This value is never mutated.
+     */
+    initialPortfolio: Portfolio;
+    /**
+     * Source of OHLCV bar data and optionally fundamentals / corporate events.
+     * `FeatureRuntime` uses this to hydrate price series before computing indicators.
+     */
+    dataFeed: DataFeed;
+    /**
+     * Order router responsible for converting `Order` objects into `Fill` records.
+     * Use `BacktestExecutor` for historical simulations or swap in a live
+     * broker implementation for paper/live trading.
+     */
+    executor: Executor;
+    /**
+     * Trading-day calendar. Used to enumerate `sessions` within `range` and to
+     * determine rebalance day boundaries via `next`.
+     */
+    calendar: Calendar;
+    /**
+     * Optional persistent indicator cache. When omitted, each `runBacktest` call
+     * recomputes all indicators from scratch. Provide `MemoryFeatureCache` (or a
+     * cross-process cache) to memoize results across multiple runs.
+     */
+    featureCache?: FeatureCache;
+    /**
+     * Bar frequency forwarded to `DataFeed.bars`. Defaults to `'1d'` when omitted.
+     * Must match the granularity expected by the strategy's indicator specs.
+     */
+    freq?: Frequency;
+    /**
+     * Optional `FeatureRuntime` instance. When provided, its accumulated bar buffer
+     * is exported on `BacktestResult.bars` for use by `runLive` (lets the streaming
+     * runtime seed its buffer from the historical bars without refetching).
+     */
+    featureRuntime?: FeatureRuntime;
+};
+/**
+ * A point-in-time snapshot of the simulation at the end of a single trading session.
+ *
+ * Each entry in `BacktestResult.snapshots` corresponds to one call of the strategy
+ * loop: `universe → features → build → executor.submit → applyFills`.
+ */
+type BacktestSnapshot = {
+    /** The session date for this snapshot (midnight UTC on the trading day). */
+    t: Date;
+    /** Portfolio state *after* fills have been applied for this session. */
+    portfolio: Portfolio;
+    /** Orders emitted by `strategy.build` during this session. */
+    orders: ReadonlyArray<Order>;
+    /** Fills returned by the executor for the orders above. */
+    fills: ReadonlyArray<Fill>;
+};
+/**
+ * The return value of `runBacktest`, containing the full simulation history
+ * and the terminal portfolio state.
+ */
+type BacktestResult<S = unknown> = {
+    /**
+     * Ordered list of snapshots, one per trading session in `range`. Empty when
+     * the calendar has no sessions in the requested range.
+     */
+    snapshots: ReadonlyArray<BacktestSnapshot>;
+    /**
+     * Portfolio after the last session's fills have been applied. Equivalent to
+     * `snapshots[snapshots.length - 1].portfolio` when there is at least one session,
+     * or `initialPortfolio` when the range is empty.
+     */
+    finalPortfolio: Portfolio;
+    /**
+     * Final value of the strategy's auxiliary state after the last `build()` call.
+     * `undefined` when the strategy is state-less (no `initialState()` defined).
+     * Used by `runLive` to seed the live runtime so the first live tick continues
+     * from the exact state the historical run ended on.
+     */
+    finalState: S | undefined;
+    /**
+     * Per-asset bar buffer accumulated by the `FeatureRuntime` during this run.
+     * Empty `Map` when no `featureRuntime` was provided in `RunBacktestOptions`.
+     * Used by `runLive` to seed its streaming `FeatureRuntime` so indicators with
+     * warmup periods (SMA(200), etc.) work on the first live tick.
+     */
+    bars: ReadonlyMap<AssetId, ReadonlyArray<Bar>>;
+};
+/**
+ * Drives a `Strategy` over a historical date range and returns a full audit trail
+ * of orders, fills, and portfolio states.
+ *
+ * The simulation loop:
+ * 1. Enumerate trading sessions via `opts.calendar.sessions(opts.range)`.
+ * 2. Call `strategy.initialState?.()` once to seed the carry-over state.
+ * 3. For each session `t`, call `strategy.universe(t, portfolio)`.
+ * 4. Await `strategy.features(universe, portfolio, t)`.
+ * 5. Call `strategy.build(features, portfolio, state, t)` to obtain orders and
+ *    the next state value. Both legacy `Order[]` returns and new `{ orders, state }`
+ *    returns are normalised — the legacy form leaves state unchanged.
+ * 6. Await `opts.executor.submit(orders, t, portfolio)` to obtain fills.
+ * 7. Apply fills to the portfolio with `applyFills`.
+ * 8. Append a `BacktestSnapshot` and advance to the next session.
+ *
+ * The portfolio is never mutated in place; each session receives the immutable
+ * result of the previous session's `applyFills`.
+ *
+ * @param opts - Backtest configuration. See {@link RunBacktestOptions}.
+ * @returns A promise that resolves to a {@link BacktestResult} containing one
+ *   snapshot per trading session, the final portfolio state, and the final
+ *   strategy state (`finalState`). Returns
+ *   `{ snapshots: [], finalPortfolio: opts.initialPortfolio, finalState: undefined }`
+ *   when the calendar has no sessions in the requested range.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   runBacktest,
+ *   fromSpec,
+ *   MemoryFeatureCache,
+ *   BacktestExecutor,
+ *   NYSEExchangeCalendar,
+ *   FeatureRuntime,
+ * } from '@livefolio/sdk';
+ *
+ * const calendar = new NYSEExchangeCalendar();
+ * const range = { from: new Date('2023-01-01'), to: new Date('2023-12-31') };
+ * const featureCache = new MemoryFeatureCache();
+ * const runtime = new FeatureRuntime({ dataFeed, featureCache, range, freq: '1d' });
+ *
+ * const strategy = fromSpec(myTacticalSpec, { runtime, calendar });
+ *
+ * const result = await runBacktest({
+ *   strategy,
+ *   range,
+ *   initialPortfolio: { cash: 100_000, positions: [] },
+ *   dataFeed,
+ *   executor: new BacktestExecutor({ dataFeed }),
+ *   calendar,
+ *   featureCache,
+ *   freq: '1d',
+ * });
+ *
+ * console.log(result.finalPortfolio.cash);
+ * console.log(result.snapshots.length); // one entry per NYSE trading day in 2023
+ * ```
+ */
+declare function runBacktest<F extends Features = Features, S = unknown>(opts: RunBacktestOptions<F, S>): Promise<BacktestResult<S>>;
+
+/**
+ * A single tick or bar update from a streaming market-data source. The bar's
+ * `t` is the **arrival timestamp** of this tick — for a 24/7 source like Yahoo
+ * WS, ticks arrive continuously and the runtime is responsible for deciding
+ * which session/bar the tick belongs to via the `Calendar`.
+ */
+type StreamingBar = {
+    /** The asset this tick is for. */
+    asset: Asset;
+    /** The bar payload — typically a 1-tick OHLCV with `open = high = low = close = <tick price>` and `volume = 0`. */
+    bar: Bar;
+};
+/**
+ * Streaming market-data source. Sibling interface to {@link DataFeed} — they
+ * are NOT a union. Historical adapters implement `DataFeed.bars()`; streaming
+ * adapters implement `StreamingDataFeed.subscribe()`. A single vendor that
+ * offers both (e.g. Polygon, Alpaca) implements both interfaces on one class.
+ *
+ * Implementations MUST guarantee:
+ * - `subscribe` yields {@link StreamingBar} objects in **ascending `bar.t` order**
+ *   per asset. Ordering across assets is not required.
+ * - The iterable is **open-ended** — it does not terminate on its own. Consumers
+ *   stop iteration by breaking the `for await` loop or by signalling cancel
+ *   through whatever mechanism the runtime provides.
+ * - Ticks may arrive **outside session hours** (24/7 sources like Yahoo WS).
+ *   Session boundary logic is the runtime's responsibility, not the adapter's.
+ *
+ * @example
+ * ```ts
+ * import type { StreamingDataFeed, Asset } from '@livefolio/sdk';
+ *
+ * const feed: StreamingDataFeed = {
+ *   async *subscribe(assets) {
+ *     while (true) {
+ *       const tick = await waitForNextTick();
+ *       yield { asset: tick.asset, bar: tick.bar };
+ *     }
+ *   },
+ * };
+ * ```
+ */
+interface StreamingDataFeed {
+    /**
+     * Subscribes to live tick updates for the given assets.
+     *
+     * **Frequency note:** This interface intentionally omits a `freq` parameter. Bar/tick aggregation
+     * is the runtime's responsibility — see the `runLive` design in
+     * `docs/specs/2026-05-02-v0.4-phase-9-streaming-design.md` Decision #1 (resolved during design).
+     * Adapters emit raw ticks at whatever cadence the vendor provides; the runtime decides which
+     * session/bar each tick belongs to via the `Calendar`. Multi-frequency streaming (sub-daily
+     * strategies) is a separate phase, currently out of scope.
+     *
+     * @param assets - The instruments to subscribe to.
+     * @returns An open-ended async iterable of {@link StreamingBar} updates.
+     */
+    subscribe(assets: ReadonlyArray<Asset>): AsyncIterable<StreamingBar>;
 }
 
-interface SimulateOptions {
-    from: string;
-    to: string;
-    portfolio: PortfolioHandle;
+/**
+ * Unified event stream from {@link runLive}. Discriminated union of two variants:
+ *
+ * - **`mark`** — emitted per tick. The strategy is run in PREVIEW mode (state
+ *   is snapshot/restored, no executor call, no portfolio commit). Use this to
+ *   render the wiggling rightmost chart point and the "if the session ended now,
+ *   the strategy would do X" preview UX.
+ * - **`snapshot`** — emitted when a tick crosses a session boundary. The
+ *   just-closed bar is finalized, `strategy.build` runs for real, orders are
+ *   submitted to the executor, fills are applied, and state advances. Same
+ *   shape as {@link BacktestSnapshot} from {@link runBacktest} (plus the
+ *   `type: 'snapshot'` discriminant), so consumers can append snapshot events
+ *   to the same chart array used by historical results.
+ */
+type LiveEvent<F extends Features = Features, _S = unknown> = {
+    type: 'mark';
+    /** Wall-clock arrival time of this tick. */
+    t: Date;
+    /** Portfolio at the start of the current session — unchanged by the preview. */
+    portfolio: Portfolio;
+    /**
+     * Per-asset accumulating close so far in the current session. Only assets
+     * that have received at least one tick this session appear in the map.
+     */
+    prices: ReadonlyMap<AssetId, number>;
+    /** Features recomputed for the in-progress session. */
+    features: F;
+    /**
+     * Orders the strategy would emit if the session closed at the current
+     * tick price. Computed from a state SNAPSHOT — the returned `state` value
+     * is discarded, so no committed state is mutated.
+     */
+    previewOrders: ReadonlyArray<Order>;
+    /**
+     * Best-effort placeholder — returns the unchanged portfolio. A future
+     * `simulateFills(orders, prices)` helper will compute the hypothetical
+     * post-rebalance NAV that would result from applying `previewOrders` at
+     * `prices`. Until then, consumers compute NAV themselves from
+     * `portfolio` + `prices`.
+     */
+    previewPortfolio: Portfolio;
+} | (BacktestSnapshot & {
+    type: 'snapshot';
+});
+/** Required inputs to {@link runLive}. */
+type RunLiveOptions<F extends Features = Features, S = unknown> = {
+    /** The strategy to drive. If its `features` method depends on a captured
+     *  `FeatureRuntime` (e.g. tactical strategies built via `fromSpec`), pass the
+     *  same runtime instance via {@link RunLiveOptions.streamingRuntime} so the
+     *  live bar buffer stays in sync with what the strategy reads. */
+    strategy: Strategy<F, S>;
+    /**
+     * Result of a prior {@link runBacktest} call. Provides the seed `portfolio`,
+     * `state`, and `bars` map for the streaming runtime.
+     */
+    history: BacktestResult<S>;
+    /** Source of streaming ticks. */
+    dataFeed: StreamingDataFeed;
+    /** Order router used at session boundaries to settle the just-closed bar. */
+    executor: Executor;
+    /** Calendar that resolves a tick's wall-clock time into its session date. */
+    calendar: Calendar;
+    /**
+     * Optional streaming {@link FeatureRuntime}. Provide this to share the
+     * runtime with the strategy — tactical strategies built via `fromSpec`
+     * capture a runtime in their `features` closure, so passing the same
+     * instance here keeps the live bar buffer in sync with what the strategy
+     * reads. When omitted, `runLive` constructs its own streaming runtime
+     * seeded from `history.bars`.
+     */
+    streamingRuntime?: FeatureRuntime;
+};
+/**
+ * Drives a {@link Strategy} against a streaming market-data source and yields
+ * a unified event stream that consumer charts can append to historical
+ * snapshots without code branching.
+ *
+ * **Lifecycle on each tick:**
+ * 1. Resolve the tick's session date via the supplied {@link Calendar} —
+ *    `calendar.previous(calendar.next(tick.t))`. This correctly handles
+ *    after-hours ticks (NYSE 17:00 ET stays in the same session) and DST
+ *    transitions.
+ * 2. If the tick crosses a session boundary, finalize the just-closed bar:
+ *    append it to the streaming `FeatureRuntime`, run `strategy.build` for
+ *    REAL (committing state), submit orders to the executor, apply fills,
+ *    and yield a `snapshot` event identical in shape to {@link BacktestSnapshot}.
+ * 3. Record the tick into the current session's accumulating bar.
+ * 4. Re-run `strategy.features` and `strategy.build` in PREVIEW mode (state
+ *    is snapshot/restored — committed state is untouched). Yield a `mark`
+ *    event with the recomputed features and preview orders.
+ *
+ * **State semantics:** preview-build always operates on a deep clone of the
+ * committed `state`. Only the boundary-crossing commit branch advances
+ * committed state. This guarantees that 1000 ticks within a single session
+ * produce 1000 marks but leave `state` exactly where the prior session-close
+ * commit left it.
+ *
+ * **FeatureRuntime:** if the strategy was built via `fromSpec` it captures its
+ * own runtime in the `features` closure. Pass that same instance via
+ * {@link RunLiveOptions.streamingRuntime} so `appendBar` calls land on the
+ * runtime the strategy actually reads. When omitted, `runLive` constructs its
+ * own streaming runtime seeded from `history.bars` — this works for hand-rolled
+ * strategies whose `features` method consults the runtime directly, but it
+ * leaves a `fromSpec` strategy reading a stale captured runtime.
+ *
+ * **Bar lineage:** the streaming `FeatureRuntime` (provided or constructed) is
+ * seeded from `history.bars`, so indicators with warmup periods (SMA(200),
+ * etc.) work on the first live tick.
+ *
+ * **Universe:** captured once at startup from
+ * `strategy.universe(anchorTime, portfolio)`, where `anchorTime` is the last
+ * historical snapshot's timestamp (or epoch zero for empty history). Dynamic
+ * universes are not yet supported in live mode.
+ *
+ * **Termination:** the iterable terminates when the underlying
+ * `StreamingDataFeed.subscribe` iterable terminates. Real adapters yield
+ * forever; tests use bounded iterables to assert specific event sequences.
+ *
+ * @param opts - Live-runtime configuration. See {@link RunLiveOptions}.
+ * @returns An open-ended `AsyncIterable<LiveEvent>`. Consumers `for await` the
+ *   stream and dispatch on `ev.type`.
+ *
+ * @example
+ * ```ts
+ * for await (const ev of runLive({ strategy, history, dataFeed, executor, calendar })) {
+ *   if (ev.type === 'mark') {
+ *     chart.updateLastBar({ t: ev.t, prices: ev.prices, previewOrders: ev.previewOrders });
+ *   } else {
+ *     chart.appendBar(ev); // BacktestSnapshot-shaped
+ *   }
+ * }
+ * ```
+ */
+declare function runLive<F extends Features = Features, S = unknown>(opts: RunLiveOptions<F, S>): AsyncIterable<LiveEvent<F, S>>;
+
+/**
+ * In-process, Map-backed implementation of {@link FeatureCache}. Caches
+ * computed indicator series in memory for the lifetime of the instance.
+ * There is no eviction policy — the cache grows until the instance is
+ * garbage-collected.
+ *
+ * **When to use**: the right choice for single-run backtests or unit tests
+ * where the full dataset fits in process memory and cross-run persistence is
+ * not required. For long-running hosted services or multi-process setups,
+ * substitute a persistent implementation (e.g. Redis-backed) that satisfies
+ * the {@link FeatureCache} interface.
+ *
+ * Cache keys are content-addressed strings composed of `(feature kind, params
+ * hash, asset scope, date range, frequency)` — see the internal
+ * `canonicalKey` function. The `invalidate` method performs prefix-based
+ * deletion using the same key segments.
+ *
+ * @example
+ * ```ts
+ * import { MemoryFeatureCache } from '@livefolio/sdk';
+ * import { FeatureRuntime } from '@livefolio/sdk/features';
+ *
+ * const cache   = new MemoryFeatureCache();
+ * const runtime = new FeatureRuntime({ feed: myDataFeed, cache });
+ * ```
+ */
+declare class MemoryFeatureCache implements FeatureCache {
+    private store;
+    get(key: FeatureKey): Promise<Series | undefined>;
+    set(key: FeatureKey, series: Series): Promise<void>;
+    invalidate(prefix: Partial<FeatureKey>): Promise<void>;
 }
-interface Trade {
-    date: string;
-    symbol: string;
-    quantity: number;
+
+/**
+ * Callback that resolves the next-open price for `asset` as seen from date `t`.
+ * {@link BacktestExecutor} calls this once per order to determine the fill price.
+ *
+ * The function should return the opening price of the first trading session
+ * strictly after `t`, along with that session's timestamp. In a typical
+ * backtest setup this reads from the same data feed used to compute features.
+ *
+ * @param asset - The instrument being filled.
+ * @param t     - The date on which the rebalance order was submitted (the
+ *                "signal date"). The fill should occur on the next open after
+ *                this date to avoid look-ahead.
+ * @returns An object with the fill timestamp `t` and the opening `price`.
+ */
+type NextOpenFn = (asset: Asset, t: Date) => Promise<{
+    t: Date;
     price: number;
-    action: 'buy' | 'sell';
-}
-interface PortfolioSnapshot {
-    value: number;
-    holdings: [TickerHandle, number][];
-    weights: [TickerHandle, number][];
-    pendingTrades: Trade[];
-}
-interface FinalState {
-    portfolio: PortfolioHandle;
-    allocation: AllocationHandle;
-    closePrices: Record<string, number>;
-    leveragedPrices: Record<string, number>;
-}
-/** Per-signal slice of a live strategy snapshot. */
-interface LiveSignalState {
-    indicator1: {
-        value: number | null;
-        date: string | null;
-    };
-    indicator2: {
-        value: number | null;
-        date: string | null;
-    };
-    isTrue: boolean;
-}
-/** Per-rule collection of live signal states, in the same order as the rule's `when` list. */
-interface LiveRuleState {
-    signals: LiveSignalState[];
-}
-/** Full live strategy view for a single evaluation date — no portfolio info. */
-interface StrategyLiveState {
-    allocation: AllocationHandle | null;
-    activeRuleIndex: number;
-    rules: LiveRuleState[];
-}
+}>;
+/**
+ * Constructor options for {@link BacktestExecutor}.
+ */
+type BacktestExecutorOptions = {
+    /** Exchange calendar used to route fills to the next open session. */
+    calendar: Calendar;
+    /**
+     * Callback that resolves the next-open price for a given asset and date.
+     * See {@link NextOpenFn} for the exact contract.
+     */
+    nextOpen: NextOpenFn;
+    /**
+     * One-way slippage in basis points applied to every fill. The fill price is
+     * adjusted by `price × (1 + sign × slippageBps / 10 000)` where `sign` is
+     * `+1` for buys and `−1` for sells. Defaults to `0`.
+     */
+    slippageBps?: number;
+    /**
+     * Flat per-share commission in the portfolio's base currency. Multiplied by
+     * the fill quantity and recorded in `Fill.fees`. Defaults to `0`.
+     */
+    perShareFee?: number;
+};
 /**
- * Combined live state returned by `SimulationHandle.pushAndPreview`: both the
- * portfolio snapshot from a `push` and the strategy evaluation at the target
- * date under the accumulated live-quote overrides.
+ * Reference {@link Executor} implementation for backtesting. Fills each order
+ * at the next-open price returned by the {@link NextOpenFn} callback, with
+ * optional slippage and per-share commissions applied.
+ *
+ * **When to use**: suitable for historical simulations and unit tests where
+ * real broker connectivity is not needed. For live or paper trading, substitute
+ * a broker-backed `Executor` that satisfies the same interface.
+ *
+ * **Fill mechanics**: for each order in `orders`, the executor calls
+ * `opts.nextOpen(asset, t)` to obtain the fill price and timestamp. The
+ * raw price is then adjusted for slippage:
+ * ```
+ * adjustedPrice = nextOpen.price × (1 + sign × slippageBps / 10 000)
+ * ```
+ * where `sign` is `+1` for net-buy direction and `−1` for net-sell direction.
+ * A flat per-share fee is added to `Fill.fees`. Orders with zero quantity are
+ * silently skipped.
+ *
+ * @example
+ * ```ts
+ * import { BacktestExecutor } from '@livefolio/sdk';
+ * import { getCalendar } from '@livefolio/sdk';
+ *
+ * const executor = new BacktestExecutor({
+ *   calendar:    getCalendar('NYSE'),
+ *   nextOpen:    async (asset, t) => {
+ *     // Return the first open bar strictly after t from your data feed.
+ *     const bar = await feed.nextBar(asset, t);
+ *     return { t: bar.t, price: bar.open };
+ *   },
+ *   slippageBps: 5,    // 0.05% one-way
+ *   perShareFee: 0.005,
+ * });
+ * ```
  */
-interface LivePreviewState extends StrategyLiveState {
-    snapshot: PortfolioSnapshot;
+declare class BacktestExecutor implements Executor {
+    private readonly opts;
+    constructor(opts: BacktestExecutorOptions);
+    submit(orders: ReadonlyArray<Order>, t: Date, portfolio: Portfolio): Promise<ReadonlyArray<Fill>>;
 }
+
 /**
- * Callback shape that `SimulationHandle.pushAndPreview` delegates to. Exists
- * purely to break the circular import between `SimulationHandle` (in this
- * file) and `StrategyHandle` (which creates simulations) — a strategy passes
- * a bound `(date, overrides) => previewLiveState(...)` into the handle.
+ * Error thrown by {@link RoutingDataFeed} when an asset cannot be routed or
+ * 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".
  */
-interface LiveEvaluator {
-    previewLiveState(date: string, overrides: Record<string, number>): Promise<StrategyLiveState>;
+declare class RoutingDataFeedError extends Error {
+    constructor(message: string);
 }
-declare class SimulationHandle {
-    readonly series: DailyBar[];
-    readonly trades: Trade[];
-    readonly startingPortfolio: PortfolioHandle;
-    private _portfolio;
-    private _currentAllocation;
-    private _lastClosePrices;
-    private _lastLeveragedPrices;
-    private _currentLeveragedPrices;
-    private _lastDate;
-    private _pushedQuotes;
-    private _liveEvaluator;
-    constructor(series: DailyBar[], trades: Trade[], startingPortfolio: PortfolioHandle, finalState?: FinalState, liveEvaluator?: LiveEvaluator);
-    push(...prices: [TickerHandle, number][]): PortfolioSnapshot;
-    /**
-     * One-call live update. Feeds portfolio-relevant ticker prices into `push`
-     * (derived from `quotes` via the running portfolio's holdings), accumulates
-     * every symbol in `quotes` into an internal override map so macro symbols
-     * (e.g. `^VIX`) persist across ticks, then delegates to the simulation's
-     * strategy for rule / signal / indicator evaluation at `date`.
-     *
-     * Without a live evaluator attached, returns just the portfolio snapshot
-     * with allocation/rules/signals empty.
-     *
-     * @param quotes Symbol → raw live price. Portfolio tickers flow through
-     *   `push` for leveraged-equity math; non-portfolio symbols are still
-     *   layered into the overlay so indicators can see them.
-     * @param options.date Target trading day to evaluate against. Defaults to
-     *   the current UTC ISO date; callers with non-UTC semantics or after-hours
-     *   rollover should supply their own.
-     */
-    metrics(options?: MetricsOptions): MetricsResult;
-    pushAndPreview(quotes: Record<string, number>, options?: {
-        date?: string;
-    }): Promise<LivePreviewState>;
+/** Function form of the routing rule. Returns the feed for `asset`, or `undefined` when no feed handles it. */
+type RoutingDataFeedRouteFn = (asset: Asset) => DataFeed | undefined;
+/** Map form of the routing rule. Keys are `Asset['kind']` discriminants. */
+type RoutingDataFeedRouteMap = Readonly<Partial<Record<Asset['kind'], DataFeed>>>;
+/**
+ * A {@link DataFeed} that delegates each call to one of several underlying
+ * feeds based on the asset. Use this to compose vendors — e.g. Yahoo for
+ * equities and FRED for macro series — behind a single `DataFeed` instance
+ * accepted by `runBacktest`, `FeatureRuntime`, and `BacktestExecutor`.
+ *
+ * Routing rules:
+ * - **Map form:** `new RoutingDataFeed({ equity: yahoo, macro: fred })`.
+ *   Keys are `asset.kind` discriminants. The 90% case.
+ * - **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.
+ *
+ * @example
+ * ```ts
+ * import { RoutingDataFeed } from '@livefolio/sdk';
+ *
+ * const feed = new RoutingDataFeed({ equity: yahooFeed, macro: fredFeed });
+ *
+ * const result = await runBacktest({
+ *   strategy, range, initialPortfolio,
+ *   dataFeed: feed,
+ *   executor,
+ *   calendar,
+ * });
+ * ```
+ */
+declare class RoutingDataFeed implements DataFeed {
+    private readonly route;
+    constructor(routes: RoutingDataFeedRouteMap | RoutingDataFeedRouteFn);
+    bars(asset: Asset, range: DateRange, freq: Frequency): AsyncGenerator<Bar>;
+    fundamentals(asset: Asset, t: Date): Promise<Fundamentals>;
+    private resolve;
 }
 
-interface StrategyRule {
-    when?: SignalHandle[];
-    hold: AllocationHandle;
+/**
+ * Error thrown by {@link RoutingStreamingDataFeed} when an asset cannot be routed.
+ */
+declare class RoutingStreamingDataFeedError extends Error {
+    constructor(message: string);
 }
-interface StrategyBar {
-    date: string;
-    allocation: AllocationHandle;
+/** Function form of the routing rule. Returns the feed for `asset`, or `undefined` when no feed handles it. */
+type RoutingStreamingDataFeedRouteFn = (asset: Asset) => StreamingDataFeed | undefined;
+/** Map form of the routing rule. Keys are `Asset['kind']` discriminants. */
+type RoutingStreamingDataFeedRouteMap = Readonly<Partial<Record<Asset['kind'], StreamingDataFeed>>>;
+/**
+ * A {@link StreamingDataFeed} that delegates `subscribe()` to one of several
+ * underlying feeds based on the asset. Use this to compose vendors — e.g.
+ * Polygon for equities and a polling adapter for macro series — behind a
+ * single `StreamingDataFeed` instance accepted by `runLive`.
+ *
+ * Routing rules:
+ * - **Map form:** `new RoutingStreamingDataFeed({ equity: polygon, macro: polling })`.
+ *   Keys are `asset.kind` discriminants. The 90% case.
+ * - **Function form:** `new RoutingStreamingDataFeed((a) => a.kind === 'macro' ? polling : polygon)`.
+ *   Use when routing depends on more than `kind` (e.g. allowlists).
+ *
+ * Assets are grouped by routed feed (by reference identity) before calling
+ * upstream `subscribe()` — so a vendor adapter that opens one socket for
+ * `[AAPL, MSFT]` keeps doing that rather than receiving one-asset-at-a-time calls.
+ *
+ * @example
+ * ```ts
+ * import { RoutingStreamingDataFeed, pollingStreamFromHistorical } from '@livefolio/sdk';
+ *
+ * const feed = new RoutingStreamingDataFeed({
+ *   equity: polygonStreaming,
+ *   macro: pollingStreamFromHistorical({ feed: fredHistorical, freq: '1d', schedule: { kind: 'session-close', calendar: nyse } }),
+ * });
+ * ```
+ */
+declare class RoutingStreamingDataFeed implements StreamingDataFeed {
+    private readonly route;
+    constructor(routes: RoutingStreamingDataFeedRouteMap | RoutingStreamingDataFeedRouteFn);
+    subscribe(assets: ReadonlyArray<Asset>): AsyncIterable<StreamingBar>;
+    private merged;
 }
-interface StrategyOptions {
+
+type PollingSchedule = {
+    kind: 'interval';
+    intervalMs: number;
+} | {
+    kind: 'session-close';
+    calendar: Calendar;
+};
+type PollingStreamOptions = {
+    /** Historical feed to poll. Each tick of the schedule calls `feed.bars(asset, …)` for each subscribed asset. */
+    feed: DataFeed;
+    /** Bar frequency to request. Single value — multi-frequency requires composing two polling streams via `RoutingStreamingDataFeed`. */
+    freq: Frequency;
+    /** When to poll. */
+    schedule: PollingSchedule;
+    /**
+     * Window-start for the first poll per asset. Subsequent polls fetch
+     * `(lastSeenT, now]` per asset. Defaults to `new Date(0)` — every bar the
+     * feed has on the first poll is yielded. For replay-then-stream, set this
+     * to your backtest range's `to` so polling picks up exactly where the
+     * backtest left off.
+     */
+    initialFrom?: Date;
+    /** Inject for tests or for accelerated-time simulations. Defaults to `() => new Date()`. */
+    now?: () => Date;
+    /** Inject for tests or for accelerated-time simulations. Defaults to `setTimeout`-based promise. */
+    sleep?: (ms: number) => Promise<void>;
+};
+declare function pollingStreamFromHistorical(opts: PollingStreamOptions): StreamingDataFeed;
+
+/**
+ * A year-derived holiday rule consumed by {@link ExchangeCalendar}. The rule
+ * is active only for years in the range `[validFrom, validUntil]` (both
+ * inclusive; omit either bound to leave it open).
+ *
+ * `resolve(year)` returns the UTC midnight `Date` for the holiday in that year,
+ * or `null` if the holiday does not occur that year (e.g. a conditional rule
+ * for Good Friday in certain years). When `observe` is `true`, a Saturday
+ * result is moved to Friday and a Sunday result is moved to Monday (standard
+ * US-style holiday observation).
+ */
+type HolidayRule = {
+    /** Human-readable name, used for debugging and logging. */
     name: string;
-    freq?: TradingFreq;
-    offset?: number;
-    rules: StrategyRule[];
-}
-declare class StrategyHandle {
-    private _linkId;
-    private _name;
-    private _freq;
-    private _offset;
-    private _rules;
-    private _storage;
-    private _market;
-    private _resolvedId;
-    private _resolvedLinkId;
-    private _resolving;
-    private _allocationMap;
-    private _cache;
-    private _cachedAsOf;
-    private _syncing;
-    constructor(storage: StorageProvider, market: MarketProvider, optionsOrLinkId: StrategyOptions | string);
-    get id(): number;
-    get link(): string;
-    get name(): string | null;
-    get freq(): TradingFreq;
-    get offset(): number;
-    get rules(): StrategyRule[];
-    marketSymbols(): string[];
-    resolve(): Promise<{
-        id: number;
-    }>;
-    private _doResolveCreate;
-    private _doResolveReference;
-    private _getLatestClosedTradingDay;
-    private _ensureFresh;
-    private _sync;
-    /**
-     * Pure evaluate — runs the same pipeline as _sync but returns the computed
-     * evaluation instead of persisting. Used by both _sync (post-close write
-     * path) and the public preview methods (pre-close read-only path).
-     *
-     * When `overrides` is `undefined` we take the write path — syncing signals
-     * through storage as normal. When `overrides` is provided (even an empty
-     * map) we take the read-only preview path: historical signal bars come
-     * straight from storage, today's bar is computed in-memory via
-     * `signal.computeAt(date, overrides, prevBool)`, and nothing is written.
-     *
-     * Incremental path: when a strategy checkpoint exists (`getLatestSeriesDate`
-     * returns non-null), only the window (lastDate, limitDate] is processed.
-     * The current allocation is carried forward from `getLatestAllocationId`.
-     * Bootstrap: when no checkpoint exists, falls back to `_evaluateCold` which
-     * runs the full-history evaluation.
-     */
-    private _evaluate;
-    private _evaluateCold;
-    private _querySeriesFromDb;
-    series(range?: DateRange): Promise<StrategyBar[]>;
-    value(date?: string): Promise<AllocationHandle | null>;
-    simulate(options: SimulateOptions): Promise<SimulationHandle>;
-    /**
-     * Preview the allocation this strategy would produce for `date` if today
-     * closed at the provided raw quote prices. Does NOT write to strategies_series,
-     * signals_series, or indicators_series. Safe to call before market close.
-     *
-     * @param date - The trading day to preview (must be in tradingDays.getRange()).
-     * @param overrides - Raw (unleveraged) live prices keyed by market symbol.
-     *   Symbols absent from this map fall back to the last stored value
-     *   (see `IndicatorHandle._resolveRawBars`).
-     * @returns The AllocationHandle for `date`, or null if the strategy has no
-     *   evaluable entry for that date.
-     */
-    previewAllocation(date: string, overrides: Record<string, number>): Promise<AllocationHandle | null>;
-    /**
-     * Read-only preview of the strategy's allocation series including `date`.
-     * Returns stored historical allocations plus an in-memory bar at `date`
-     * computed via the same overrides-based preview path as `previewAllocation`.
-     *
-     * @param date - Target trading day to splice in-memory.
-     * @param overrides - Raw (unleveraged) quotes keyed by market symbol.
-     * @param range - Optional filter applied to the returned bars.
-     */
-    previewSeries(date: string, overrides: Record<string, number>, range?: DateRange): Promise<StrategyBar[]>;
-    /**
-     * Full live strategy view at `date` under live-quote `overrides`: the active
-     * allocation, the index of the rule that fired (or fallback), and per-rule
-     * per-signal indicator values + truth. Computed entirely through the
-     * overrides preview path — no writes to any `*_series` tables.
-     *
-     * Threshold indicators have their date suppressed (`null`) since their
-     * synthetic series runs over every trading day in storage including future
-     * dates and would report a far-future date for the last bar.
-     */
-    previewLiveState(date: string, overrides: Record<string, number>): Promise<StrategyLiveState>;
-    private _fetchPricesForTickers;
-    private _fetchRawClosePrices;
-}
+    /** Returns the UTC midnight `Date` for this holiday in `year`, or `null` to skip. */
+    resolve: (year: number) => Date | null;
+    /** First year (inclusive) this rule applies. Defaults to −∞. */
+    validFrom?: number;
+    /** Last year (inclusive) this rule applies. Defaults to +∞. */
+    validUntil?: number;
+    /** When `true`, Saturday dates are moved to Friday, Sunday dates to Monday. */
+    observe?: boolean;
+};
+/**
+ * A year-derived early-close rule consumed by {@link ExchangeCalendar}. Follows
+ * the same validity bounds and `resolve` contract as {@link HolidayRule}, but
+ * instead of marking a day closed entirely it overrides the session close time
+ * to `closeAt` for the matched date.
+ */
+type SpecialClose = {
+    /** Human-readable name, used for debugging and logging. */
+    name: string;
+    /** Returns the UTC midnight `Date` for this early-close day in `year`, or `null` to skip. */
+    resolve: (year: number) => Date | null;
+    /** The overridden close time in local exchange time. */
+    closeAt: TimeOfDay;
+    /** First year (inclusive) this rule applies. Defaults to −∞. */
+    validFrom?: number;
+    /** Last year (inclusive) this rule applies. Defaults to +∞. */
+    validUntil?: number;
+};
+/**
+ * A year-derived late-open rule consumed by {@link ExchangeCalendar}. Follows
+ * the same validity bounds and `resolve` contract as {@link HolidayRule}, but
+ * overrides the session open time to `openAt` for the matched date.
+ */
+type SpecialOpen = {
+    /** Human-readable name, used for debugging and logging. */
+    name: string;
+    /** Returns the UTC midnight `Date` for this late-open day in `year`, or `null` to skip. */
+    resolve: (year: number) => Date | null;
+    /** The overridden open time in local exchange time. */
+    openAt: TimeOfDay;
+    /** First year (inclusive) this rule applies. Defaults to −∞. */
+    validFrom?: number;
+    /** Last year (inclusive) this rule applies. Defaults to +∞. */
+    validUntil?: number;
+};
+/**
+ * Map of `YYYY-MM-DD` date strings to override times. Used for one-off
+ * historical specials (e.g. a single early close due to a snowstorm) that do
+ * not fit a repeating year-derived rule. Keys must be in `YYYY-MM-DD` format
+ * in UTC.
+ */
+type AdhocTimeOverrides = ReadonlyMap<string, TimeOfDay>;
 
-type TreasuryTenor = Extract<IndicatorType, 'T3M' | 'T6M' | 'T1Y' | 'T2Y' | 'T3Y' | 'T5Y' | 'T7Y' | 'T10Y' | 'T20Y' | 'T30Y'>;
-type CalendarPeriod = Extract<IndicatorType, 'Month' | 'Day of Week' | 'Day of Month' | 'Day of Year'>;
-interface IndicatorOpts {
-    delay?: number;
+/**
+ * Abstract base class for exchange trading calendars. Implements the full
+ * {@link Calendar} interface by composing up to nine overridable hooks that
+ * subclasses provide. Concrete implementations ship for {@link NYSEExchangeCalendar}
+ * and {@link LSEExchangeCalendar}; additional exchanges can be added by
+ * extending this class.
+ *
+ * **Per-year caching**: holiday sets and special-session maps are computed once
+ * per calendar year and stored in private Maps, so repeated calls to `isOpen`,
+ * `next`, or `sessions` within the same year are cheap.
+ *
+ * **Hook resolution order** (adhoc beats rule, rule beats regular):
+ * 1. `adhocHolidays()` / `specialClosesAdhoc()` / `specialOpensAdhoc()` —
+ *    `YYYY-MM-DD` string sets/maps populated once at first access.
+ * 2. `regularHolidays()` / `specialCloses()` / `specialOpens()` —
+ *    year-derived rule arrays applied per year via the resolver helpers.
+ * 3. `regularOpen(date)` / `regularClose(date)` / `weekmask(date)` —
+ *    per-date fallbacks that subclasses override to encode era-varying session
+ *    times and trading-day sets.
+ *
+ * **Extending**: override only the hooks you need. All hooks have no-op / sensible
+ * defaults (Mon–Fri weekmask, 09:30–16:00 session) so a minimal subclass need
+ * only set `name`, `tz`, and `regularHolidays()`.
+ */
+declare abstract class ExchangeCalendar implements Calendar {
+    /** Short exchange name used as the registry key in {@link getCalendar}. */
+    abstract readonly name: string;
+    /** IANA timezone identifier, e.g. `'America/New_York'` or `'Europe/London'`. */
+    abstract readonly tz: string;
+    private readonly holidayCache;
+    private readonly specialCloseCache;
+    private readonly specialOpenCache;
+    private adhocHolidaysCache;
+    private adhocSpecialClosesCache;
+    private adhocSpecialOpensCache;
+    /**
+     * Returns the ordered list of year-derived holiday rules for this exchange.
+     * The base implementation returns an empty array (no regular holidays). Override
+     * to supply the full rule set; each {@link HolidayRule} in the array is applied
+     * via {@link resolveHolidays} once per calendar year and cached. Rules may be
+     * era-bounded via `validFrom` / `validUntil`.
+     */
+    protected regularHolidays(): ReadonlyArray<HolidayRule>;
+    /**
+     * Returns the set of `YYYY-MM-DD` strings for one-off full-day closures that
+     * do not fit a repeating rule (e.g. presidential funerals, natural disasters).
+     * The base implementation returns an empty set. Override with the complete
+     * historical adhoc list for the exchange. This method is called at most once
+     * per `ExchangeCalendar` instance; the result is cached.
+     */
+    protected adhocHolidays(): ReadonlySet<string>;
+    /**
+     * Returns the ordered list of year-derived early-close rules for this exchange.
+     * The base implementation returns an empty array. Override to supply rules such
+     * as "day after Thanksgiving closes at 13:00". Results are computed once per
+     * year and cached; each rule is applied via {@link resolveSpecialCloses}.
+     */
+    protected specialCloses(): ReadonlyArray<SpecialClose>;
+    /**
+     * Returns the map of `YYYY-MM-DD` strings to override close times for
+     * one-off early-close days that do not fit a repeating rule. The base
+     * implementation returns an empty map. Override with the historical adhoc
+     * set for the exchange. Called at most once per instance; result is cached.
+     */
+    protected specialClosesAdhoc(): AdhocTimeOverrides;
+    /**
+     * Returns the ordered list of year-derived late-open rules for this exchange.
+     * The base implementation returns an empty array. Override to supply rules such
+     * as "delayed open due to a moment of silence". Results are computed once per
+     * year and cached; each rule is applied via {@link resolveSpecialOpens}.
+     */
+    protected specialOpens(): ReadonlyArray<SpecialOpen>;
+    /**
+     * Returns the map of `YYYY-MM-DD` strings to override open times for
+     * one-off late-open days that do not fit a repeating rule. The base
+     * implementation returns an empty map. Override with the historical adhoc
+     * set for the exchange. Called at most once per instance; result is cached.
+     */
+    protected specialOpensAdhoc(): AdhocTimeOverrides;
+    /**
+     * Returns the default open time in local exchange time for `date` when no
+     * special-open rule matches. The base implementation returns 09:30. Override
+     * to encode era-varying session times (e.g. NYSE opened at 10:00 before
+     * 1985-09-30).
+     *
+     * @param date - UTC midnight `Date` for the trading day being queried.
+     */
+    protected regularOpen(_date: Date): TimeOfDay;
+    /**
+     * Returns the default close time in local exchange time for `date` when no
+     * special-close rule matches. The base implementation returns 16:00. Override
+     * to encode era-varying session times (e.g. NYSE closed at 15:00 before
+     * 1952-09-29, and at 15:30 until 1974-01-02).
+     *
+     * @param date - UTC midnight `Date` for the trading day being queried.
+     */
+    protected regularClose(_date: Date): TimeOfDay;
+    /**
+     * Returns the set of weekday indices (using `Date.getUTCDay()` convention:
+     * 0 = Sunday, 1 = Monday, …, 6 = Saturday) that are regular trading days.
+     * The base implementation returns `{1, 2, 3, 4, 5}` (Mon–Fri). Override to
+     * encode historical six-day trading weeks (e.g. NYSE traded Mon–Sat before
+     * 1952-09-29, keyed by `date` so the shift is era-aware).
+     *
+     * @param date - UTC midnight `Date` for the day being tested.
+     */
+    protected weekmask(_date: Date): ReadonlySet<number>;
+    private getAdhocHolidays;
+    private getAdhocSpecialCloses;
+    private getAdhocSpecialOpens;
+    /**
+     * Cached lookup of regular-holiday timestamps for the given year.
+     * Assumes `regularHolidays()` returns the same rule list on every call.
+     */
+    private holidaysForYear;
+    private specialClosesForYear;
+    private specialOpensForYear;
+    private normalize;
+    /** Returns `true` when `t` falls on a regular trading day (weekmask check, then holiday check). */
+    isOpen(t: Date): boolean;
+    /** Returns the first trading day strictly after `t`. */
+    next(t: Date): Date;
+    /** Returns the first trading day strictly before `t`. */
+    previous(t: Date): Date;
+    /**
+     * Returns UTC midnight `Date` objects for every trading day in
+     * `[range.from, range.to)`. The `from` bound is inclusive; `to` is exclusive.
+     */
+    sessions(range: DateRange): ReadonlyArray<Date>;
+    schedule(range: DateRange): ReadonlyArray<Session>;
+    isEarlyClose(t: Date): boolean;
+    /** Adhoc overrides win over rule-driven; both win over `regularOpen(date)`. */
+    private openTimeFor;
+    /** Adhoc overrides win over rule-driven; both win over `regularClose(date)`. */
+    private closeTimeFor;
+    private localizedTimestamp;
 }
-interface LivefolioClient {
-    ticker(symbol: string, leverage?: number): TickerHandle;
-    sma(ticker: TickerHandle, lookback: number, opts?: IndicatorOpts): IndicatorHandle;
-    ema(ticker: TickerHandle, lookback: number, opts?: IndicatorOpts): IndicatorHandle;
-    price(ticker: TickerHandle, opts?: IndicatorOpts): IndicatorHandle;
-    returns(ticker: TickerHandle, lookback: number, opts?: IndicatorOpts): IndicatorHandle;
-    volatility(ticker: TickerHandle, lookback: number, opts?: IndicatorOpts): IndicatorHandle;
-    drawdown(ticker: TickerHandle, lookback: number, opts?: IndicatorOpts): IndicatorHandle;
-    rsi(ticker: TickerHandle, lookback: number, opts?: IndicatorOpts): IndicatorHandle;
-    vix(opts?: IndicatorOpts): IndicatorHandle;
-    vix3m(opts?: IndicatorOpts): IndicatorHandle;
-    treasury(tenor: TreasuryTenor, opts?: IndicatorOpts): IndicatorHandle;
-    calendar(period: CalendarPeriod, opts?: IndicatorOpts): IndicatorHandle;
-    threshold(value: number, unit?: Unit): IndicatorHandle;
-    gt(ind1: IndicatorHandle, ind2: IndicatorHandle, tolerance?: number): SignalHandle;
-    lt(ind1: IndicatorHandle, ind2: IndicatorHandle, tolerance?: number): SignalHandle;
-    eq(ind1: IndicatorHandle, ind2: IndicatorHandle, tolerance?: number): SignalHandle;
-    allocation(...holdings: [TickerHandle, number][]): AllocationHandle;
-    portfolio(...holdings: [TickerHandle, number][]): PortfolioHandle;
-    strategy(linkId: string): StrategyHandle;
-    strategy(options: StrategyOptions): StrategyHandle;
-    strategy(optionsOrLinkId: string | StrategyOptions): StrategyHandle;
+
+/**
+ * New York Stock Exchange (NYSE) trading-day calendar covering 1885-01-01 to
+ * the present. Also applicable to NYSE-equivalent venues (NASDAQ, BATS, DJIA,
+ * DOW). Faithful port of `pandas_market_calendars`' `nyse.py`.
+ *
+ * **Era boundaries:**
+ * - Weekmask: Mon–Sat through 1952-09-28; Mon–Fri from 1952-09-29 onward
+ *   (Saturday trading retired on that date).
+ * - Regular open: 10:00 ET before 1985-09-30; 09:30 ET from 1985-09-30 onward.
+ * - Regular close: 15:00 ET before 1952-09-29; 15:30 ET through 1973-12-31;
+ *   16:00 ET from 1974-01-02 onward. Saturday closes (pre-1952) are
+ *   approximated as 12:00.
+ *
+ * Holiday coverage includes the full set of regular (rule-derived) and adhoc
+ * (literal date set) closures sourced from `pandas_market_calendars`, spanning
+ * historical events from the Ulysses Grant funeral (1885) through the Jimmy
+ * Carter national day of mourning (2025).
+ */
+declare class NYSEExchangeCalendar extends ExchangeCalendar {
+    readonly name = "NYSE";
+    readonly tz = "America/New_York";
+    protected regularHolidays(): ReadonlyArray<HolidayRule>;
+    protected adhocHolidays(): ReadonlySet<string>;
+    protected specialCloses(): ReadonlyArray<SpecialClose>;
+    protected specialClosesAdhoc(): AdhocTimeOverrides;
+    protected specialOpens(): ReadonlyArray<SpecialOpen>;
+    protected specialOpensAdhoc(): AdhocTimeOverrides;
+    protected regularOpen(date: Date): TimeOfDay;
+    protected regularClose(date: Date): TimeOfDay;
+    protected weekmask(date: Date): ReadonlySet<number>;
 }
-interface LivefolioClientOptions {
-    storage: StorageProvider;
-    market: MarketProvider;
+
+/**
+ * London Stock Exchange (LSE) trading-day calendar. Faithful port of
+ * `pandas_market_calendars`' `lse.py` and `holidays/uk.py`. Historical
+ * coverage begins 1801-01-01, aligned with the start of the modern exchange
+ * after the Banking and Financial Dealings Act 1971 codified the current
+ * bank-holiday framework.
+ *
+ * **Session**: 08:00–16:30 Europe/London. The exchange observes BST (UTC+1)
+ * in summer and GMT (UTC+0) in winter — DST handling is delegated to luxon via
+ * the `Europe/London` IANA timezone, so wall-clock session times are stable
+ * across the DST transition while their UTC equivalents shift by one hour.
+ *
+ * **Early closes**: Christmas Eve (Dec 24) and New Year's Eve (Dec 31) close
+ * at 12:30. Both use `previous_friday` observance — when the calendar date
+ * falls on a weekend, the early close moves to the prior Friday.
+ *
+ * **Era boundaries**: bank-holiday exceptions for Royal Jubilees and VE-Day
+ * anniversaries are implemented by splitting affected `Spring Bank Holiday`
+ * and `Early May Bank Holiday` rules into era-bounded shards (matching
+ * upstream `start_date` / `end_date` markers) and adding the displaced dates
+ * as adhoc closures.
+ */
+declare class LSEExchangeCalendar extends ExchangeCalendar {
+    readonly name = "LSE";
+    readonly tz = "Europe/London";
+    protected regularHolidays(): ReadonlyArray<HolidayRule>;
+    protected adhocHolidays(): ReadonlySet<string>;
+    protected specialCloses(): ReadonlyArray<SpecialClose>;
+    protected specialClosesAdhoc(): AdhocTimeOverrides;
+    protected specialOpens(): ReadonlyArray<SpecialOpen>;
+    protected specialOpensAdhoc(): AdhocTimeOverrides;
+    protected regularOpen(_date: Date): TimeOfDay;
+    protected regularClose(_date: Date): TimeOfDay;
+    protected weekmask(_date: Date): ReadonlySet<number>;
 }
-declare function createClient(options: LivefolioClientOptions): LivefolioClient;
-
-type StreamStatus = 'connected' | 'disconnected' | 'reconnecting';
-interface PriceStream {
-    subscribe(...symbols: string[]): void;
-    unsubscribe(...symbols: string[]): void;
-    on(event: 'tick', cb: (symbol: string, price: number, time: string) => void): void;
-    on(event: 'status', cb: (status: StreamStatus) => void): void;
-    on(event: 'error', cb: (error: Error) => void): void;
-    off(event: 'tick', cb: (symbol: string, price: number, time: string) => void): void;
-    off(event: 'status', cb: (status: StreamStatus) => void): void;
-    off(event: 'error', cb: (error: Error) => void): void;
-    close(): void;
+
+/**
+ * Union of supported exchange names accepted by {@link getCalendar}.
+ *
+ * - `'NYSE'` — New York Stock Exchange (and NYSE-equivalent venues).
+ * - `'LSE'`  — London Stock Exchange.
+ */
+type ExchangeName = 'NYSE' | 'LSE';
+/**
+ * Returns a new instance of the {@link ExchangeCalendar} registered under
+ * `name`. Acts as a simple factory / registry for the two built-in calendar
+ * implementations.
+ *
+ * Supported exchange names: `'NYSE'` ({@link NYSEExchangeCalendar}) and
+ * `'LSE'` ({@link LSEExchangeCalendar}). TypeScript's exhaustive switch
+ * prevents unknown names from compiling.
+ *
+ * @param name - One of the supported {@link ExchangeName} values.
+ * @returns A fresh `ExchangeCalendar` instance for the named exchange.
+ *
+ * @example
+ * ```ts
+ * import { getCalendar } from '@livefolio/sdk';
+ *
+ * const nyse = getCalendar('NYSE');
+ * console.log(nyse.isOpen(new Date('2024-07-04'))); // false — US Independence Day
+ *
+ * const lse = getCalendar('LSE');
+ * console.log(lse.isOpen(new Date('2024-12-25'))); // false — Christmas Day
+ * ```
+ */
+declare function getCalendar(name: ExchangeName): ExchangeCalendar;
+
+/**
+ * 24/7 calendar where every day is a single session running midnight UTC to
+ * the next midnight UTC. Suitable for crypto strategies (BTC, ETH) and any
+ * always-on market.
+ *
+ * - `isOpen(t)` always returns `true`.
+ * - `next(t)` returns midnight UTC of the day after `t`.
+ * - `previous(t)` returns midnight UTC of the day before `t`.
+ * - `sessions(range)` returns one Date per day in `[range.from, range.to)`.
+ * - `schedule(range)` returns full Sessions with `open`/`close` at midnight UTC.
+ * - `isEarlyClose(t)` always returns `false`.
+ */
+declare class Crypto24x7Calendar implements Calendar {
+    isOpen(_t: Date): boolean;
+    next(t: Date): Date;
+    previous(t: Date): Date;
+    sessions(range: DateRange): ReadonlyArray<Date>;
+    schedule(range: DateRange): ReadonlyArray<Session>;
+    isEarlyClose(_t: Date): boolean;
 }
 
-declare function allocationsEqual(a: AllocationHandle | null, b: AllocationHandle | null): boolean;
+/**
+ * A reference to an asset within a {@link TacticalSpec}. Unlike the runtime
+ * {@link Asset} type, `AssetRef` is the spec-form representation: it lives
+ * inside serialized JSON specs and carries only the fields a spec author
+ * needs to declare.
+ *
+ * `id` is the stable opaque identifier (see {@link AssetId}); `symbol` is the
+ * human-readable ticker; `exchange` is optional. `kind` selects the asset
+ * variant; absent `kind` defaults to `'equity'` for backward compatibility
+ * with v0.4 specs authored before macro support landed.
+ */
+type AssetRef = {
+    /** Stable opaque asset identifier matching {@link AssetId}. */
+    id: AssetId;
+    /** Human-readable ticker symbol, e.g. `'AAPL'`. */
+    symbol: string;
+    /** Optional MIC or common exchange name, e.g. `'NYSE'`. Equity-only. */
+    exchange?: string;
+    /**
+     * Asset class. Defaults to `'equity'` when omitted. Set to `'macro'` to
+     * author FRED-style time-series assets that route to a non-equity
+     * `DataFeed` (typically via `RoutingDataFeed`).
+     */
+    kind?: 'equity' | 'macro';
+};
+/**
+ * A simulated leveraged or expense-adjusted asset that the runtime synthesizes
+ * on-the-fly from its `underlying` data feed. The bar stream is computed by
+ * {@link withSynthetics}, which wraps a real {@link DataFeed} and intercepts
+ * requests for the synthetic's `id`.
+ *
+ * The synthesized daily close is:
+ * ```
+ * close_t = close_{t-1} × (1 + leverage × underlyingReturn_t) × (1 − expense/252)
+ * ```
+ *
+ * @example
+ * ```ts
+ * import type { SyntheticAsset } from '@livefolio/sdk';
+ *
+ * const qqq3x: SyntheticAsset = {
+ *   id:         'QQQ_3X',
+ *   symbol:     'QQQ3X',
+ *   underlying: { id: 'QQQ', symbol: 'QQQ' },
+ *   leverage:   3,
+ *   expense:    0.0095,  // 0.95% annual
+ * };
+ * ```
+ */
+type SyntheticAsset = {
+    /** Stable ID for this synthetic; must be unique in the spec universe. */
+    id: AssetId;
+    /** Display symbol for this synthetic. */
+    symbol: string;
+    /** Reference to the real asset whose returns are scaled. */
+    underlying: AssetRef;
+    /** Daily return multiplier (e.g. `3` for 3× leverage, `-1` for inverse). */
+    leverage: number;
+    /** Annual expense ratio as a decimal (e.g. `0.0095` for 0.95%). Defaults to 0. */
+    expense?: number;
+    /** When set, orders are routed to this proxy asset instead of the synthetic id. */
+    tradeAs?: AssetRef;
+};
+/**
+ * Cadence at which the strategy is allowed to rebalance.
+ *
+ * - `'Daily'`     — every trading day
+ * - `'Weekly'`    — last trading day of each ISO week
+ * - `'Monthly'`   — last trading day of each calendar month
+ * - `'Quarterly'` — last trading day of each calendar quarter
+ * - `'Yearly'`    — last trading day of each calendar year
+ */
+type RebalanceFrequency = 'Daily' | 'Weekly' | 'Monthly' | 'Quarterly' | 'Yearly';
+/**
+ * Controls when the strategy is permitted to issue rebalance orders.
+ * If omitted from a {@link TacticalSpec}, the default is `{ frequency: 'Daily' }`.
+ *
+ * @see {@link isRebalanceDay} for the trading-calendar-aware gate implementation.
+ */
+type RebalanceConfig = {
+    /** How often the strategy may rebalance. */
+    frequency: RebalanceFrequency;
+};
+/**
+ * A single feature entry in a {@link TacticalSpec}. Each variant declares the
+ * indicator kind, the asset to compute it on, and the time-series lookup
+ * parameters. The `id` is the name used to reference the computed value in
+ * {@link FeatureRef} inside the rule tree.
+ *
+ * Supported variants:
+ * - `price`      — most-recent closing price
+ * - `sma`        — simple moving average over `period` trading days
+ * - `ema`        — exponential moving average over `period` trading days
+ * - `rsi`        — relative strength index over `period` trading days
+ * - `return`     — cumulative or log return over `period` trading days (see {@link ReturnMode})
+ * - `volatility` — annualised rolling standard deviation over `period` trading days
+ * - `drawdown`   — peak-to-trough drawdown over `period` trading days
+ *
+ * The optional `delay` shifts the lookup back by that many bars (0 = current
+ * bar, 1 = previous bar, etc.). Useful for avoiding look-ahead bias when using
+ * end-of-day prices.
+ */
+type TacticalFeatureSpec = {
+    id: string;
+    kind: 'price';
+    asset: AssetRef;
+    delay?: number;
+} | {
+    id: string;
+    kind: 'sma';
+    asset: AssetRef;
+    period: number;
+    delay?: number;
+} | {
+    id: string;
+    kind: 'ema';
+    asset: AssetRef;
+    period: number;
+    delay?: number;
+} | {
+    id: string;
+    kind: 'rsi';
+    asset: AssetRef;
+    period: number;
+    delay?: number;
+} | {
+    id: string;
+    kind: 'return';
+    asset: AssetRef;
+    period: number;
+    mode?: ReturnMode;
+    delay?: number;
+} | {
+    id: string;
+    kind: 'volatility';
+    asset: AssetRef;
+    period: number;
+    delay?: number;
+} | {
+    id: string;
+    kind: 'drawdown';
+    asset: AssetRef;
+    period: number;
+    delay?: number;
+};
+/**
+ * Union of all indicator kind strings that can appear in a
+ * {@link TacticalFeatureSpec}. Derived automatically from the spec union so it
+ * stays in sync.
+ */
+type TacticalFeatureKind = TacticalFeatureSpec['kind'];
+/**
+ * A reference to a computed feature value within a rule node. The `ref` string
+ * must match an `id` declared in the `features` array of the enclosing
+ * {@link TacticalSpec}. At evaluation time the runtime replaces the ref with
+ * the resolved numeric value.
+ *
+ * @see {@link Comparison} where `FeatureRef` is accepted as an operand.
+ */
+type FeatureRef = {
+    ref: string;
+};
+/**
+ * Binary comparison operator used in a {@link Comparison} node.
+ *
+ * - `'gt'`  — strictly greater than (`l > r`)
+ * - `'lt'`  — strictly less than (`l < r`)
+ * - `'gte'` — greater than or equal to (`l >= r`)
+ * - `'lte'` — less than or equal to (`l <= r`)
+ */
+type ComparisonOp = 'gt' | 'lt' | 'gte' | 'lte';
+/**
+ * Hysteresis band applied to a {@link Comparison} with `op: 'gt'` or `op: 'lt'`.
+ * Once the comparison has flipped, it will not flip back until the left operand
+ * exits the tolerance band around the right operand.
+ *
+ * `mode: 'absolute'` defines a ±`value` band around `right`.
+ * `mode: 'relative'` defines a ±`value`% band (i.e. `value` is a percentage).
+ *
+ * A `Tolerance` requires the parent {@link Comparison} to carry a stable `id`
+ * so the runtime can persist the last-known state across rebalance periods.
+ */
+type Tolerance = {
+    /** Half-width of the hysteresis band. */
+    value: number;
+    /** `'absolute'` uses raw units; `'relative'` uses a percentage of `right`. */
+    mode: 'absolute' | 'relative';
+};
+/**
+ * A binary comparison between two operands. Each operand is either a literal
+ * number or a {@link FeatureRef} resolved at evaluation time. The result is
+ * `true` when `left op right` holds.
+ *
+ * When `tolerance` is provided the comparison implements hysteresis — the
+ * result is sticky and only changes when the left operand exits the band. A
+ * stable `id` is required in that case so {@link RuleTreeState} can track the
+ * last outcome.
+ *
+ * @example
+ * ```ts
+ * import type { Comparison } from '@livefolio/sdk';
+ *
+ * // Feature "sma200" > feature "sma50"
+ * const cond: Comparison = {
+ *   op:    'gt',
+ *   left:  { ref: 'sma200' },
+ *   right: { ref: 'sma50' },
+ * };
+ * ```
+ */
+type Comparison = {
+    /** Which binary operator to apply. */
+    op: ComparisonOp;
+    /** Left-hand operand — a feature reference or a literal number. */
+    left: FeatureRef | number;
+    /** Right-hand operand — a feature reference or a literal number. */
+    right: FeatureRef | number;
+    /**
+     * Optional hysteresis band. Requires `op` to be `'gt'` or `'lt'` and
+     * requires `id` to be set.
+     */
+    tolerance?: Tolerance;
+    /**
+     * Stable identifier used to persist comparison state across steps when
+     * `tolerance` is set. Must be unique within the rule tree.
+     */
+    id?: string;
+};
+/**
+ * A leaf node in a {@link RuleNode} tree that terminates evaluation and
+ * returns a target weight allocation. `weights` is a map from asset IDs to
+ * fractional weights; weights should sum to 1 for a fully-invested portfolio,
+ * but the runtime does not enforce this constraint.
+ *
+ * @example
+ * ```ts
+ * import type { AllocateNode } from '@livefolio/sdk';
+ *
+ * // 60% equities, 40% bonds
+ * const node: AllocateNode = {
+ *   op:      'allocate',
+ *   weights: { SPY: 0.6, TLT: 0.4 },
+ * };
+ * ```
+ */
+type AllocateNode = {
+    op: 'allocate';
+    /** Map from asset ID to target portfolio weight (0–1). */
+    weights: Record<AssetId, number>;
+};
+/**
+ * A branching node in a {@link RuleNode} tree. Evaluates `cond` and recurses
+ * into `then` when the condition is true, or into `else` otherwise. Nesting
+ * `IfNode` trees builds arbitrary decision logic over computed features.
+ *
+ * @example
+ * ```ts
+ * import type { IfNode } from '@livefolio/sdk';
+ *
+ * const node: IfNode = {
+ *   op:   'if',
+ *   cond: { op: 'gt', left: { ref: 'sma50' }, right: { ref: 'sma200' } },
+ *   then: { op: 'allocate', weights: { SPY: 1 } },
+ *   else: { op: 'allocate', weights: { SHY: 1 } },
+ * };
+ * ```
+ */
+type IfNode = {
+    op: 'if';
+    /** Condition to evaluate. */
+    cond: Comparison;
+    /** Sub-tree evaluated when `cond` is true. */
+    then: RuleNode;
+    /** Sub-tree evaluated when `cond` is false. */
+    else: RuleNode;
+};
+/**
+ * A node in the tactical rule tree. Either a branching {@link IfNode} or a
+ * terminal {@link AllocateNode}.
+ *
+ * - `op: 'if'`       — see {@link IfNode}
+ * - `op: 'allocate'` — see {@link AllocateNode}
+ */
+type RuleNode = AllocateNode | IfNode;
+/**
+ * A fully self-contained declaration of a tactical allocation strategy. Plain
+ * data — no methods, no closures. Pass to {@link fromSpec} to obtain a
+ * runnable {@link Strategy}.
+ *
+ * The dialect version distinguishes `'tactical/v0'` (deprecated, byte-for-byte
+ * equivalent to v1, emits a one-time console warning) from `'tactical/v1'` (current).
+ *
+ * @example
+ * ```ts
+ * import type { TacticalSpec } from '@livefolio/sdk';
+ *
+ * const spec: TacticalSpec = {
+ *   kind:     'tactical/v1',
+ *   universe: [
+ *     { id: 'SPY', symbol: 'SPY' },
+ *     { id: 'SHY', symbol: 'SHY' },
+ *   ],
+ *   rebalance: { frequency: 'Monthly' },
+ *   features: [
+ *     { id: 'spy_sma200', kind: 'sma', asset: { id: 'SPY', symbol: 'SPY' }, period: 200 },
+ *     { id: 'spy_price',  kind: 'price', asset: { id: 'SPY', symbol: 'SPY' } },
+ *   ],
+ *   rules: {
+ *     op:   'if',
+ *     cond: { op: 'gt', left: { ref: 'spy_price' }, right: { ref: 'spy_sma200' } },
+ *     then: { op: 'allocate', weights: { SPY: 1 } },
+ *     else: { op: 'allocate', weights: { SHY: 1 } },
+ *   },
+ * };
+ * ```
+ */
+type TacticalSpec = {
+    /**
+     * Dialect version. Use `'tactical/v1'`. `'tactical/v0'` is accepted but
+     * deprecated and will emit a one-time warning.
+     */
+    kind: 'tactical/v0' | 'tactical/v1';
+    /** Ordered list of assets eligible for allocation. */
+    universe: AssetRef[];
+    /** Optional synthetic assets whose bar data is derived from an underlying. */
+    synthetics?: SyntheticAsset[];
+    /** Rebalance cadence. Defaults to `{ frequency: 'Daily' }` when omitted. */
+    rebalance?: RebalanceConfig;
+    /** Named feature computations referenced by the rule tree. */
+    features: TacticalFeatureSpec[];
+    /** Root of the rule tree that maps resolved feature values to target weights. */
+    rules: RuleNode;
+};
+/**
+ * Persistent state carried across rebalance steps for all named {@link Comparison}
+ * nodes that use hysteresis (`tolerance` set). Maps `comparison.id` to the last
+ * evaluated outcome: `1` = condition was true, `0` = condition was false.
+ *
+ * Managed internally by {@link fromSpec}; exposed as a type for testing and
+ * for callers that drive {@link evaluateRuleTree} directly.
+ */
+type RuleTreeState = ReadonlyMap<string, 0 | 1>;
 
-declare function computeRebalanceDates(tradingDays: string[], freq: TradingFreq, offset: number): Set<string>;
+/**
+ * Evaluates a {@link RuleNode} tree against a resolved set of feature values
+ * and returns the target allocation weights together with the updated
+ * hysteresis state.
+ *
+ * The tree is walked depth-first. At each {@link IfNode} the comparison is
+ * evaluated (with hysteresis applied when `tolerance` and `id` are present)
+ * and the walk follows either `then` or `else`. Evaluation terminates at an
+ * {@link AllocateNode} whose `weights` map is returned verbatim.
+ *
+ * Hysteresis: when a {@link Comparison} carries a `tolerance`, the previous
+ * outcome in `state` is used to decide whether to flip the result. The updated
+ * outcomes for all visited comparisons are collected in the returned `state` map.
+ *
+ * Throws if a {@link FeatureRef} resolves to `undefined` (the caller should
+ * suppress this with a guard or catch-block, as {@link fromSpec} does).
+ *
+ * @param rules  - Root of the rule tree to evaluate.
+ * @param values - Resolved feature values, keyed by feature id. Must contain
+ *   every `ref` string used in the tree; missing keys throw.
+ * @param state  - Prior hysteresis state from the previous evaluation step.
+ *   Pass an empty `Map` on the first call.
+ * @returns An object with:
+ *   - `weights` — target portfolio weights as a `Map<AssetId, number>`.
+ *   - `state`   — updated {@link RuleTreeState} to pass to the next step.
+ *
+ * @example
+ * ```ts
+ * import { evaluateRuleTree } from '@livefolio/sdk';
+ * import type { RuleNode, RuleTreeState } from '@livefolio/sdk';
+ *
+ * const rules: RuleNode = {
+ *   op:   'if',
+ *   cond: { op: 'gt', left: { ref: 'price' }, right: { ref: 'sma200' } },
+ *   then: { op: 'allocate', weights: { SPY: 1 } },
+ *   else: { op: 'allocate', weights: { SHY: 1 } },
+ * };
+ *
+ * let state: RuleTreeState = new Map();
+ * const values = new Map([['price', 450], ['sma200', 420]]);
+ * const result = evaluateRuleTree(rules, values, state);
+ * // result.weights → Map { 'SPY' => 1 }
+ * state = result.state;
+ * ```
+ */
+declare function evaluateRuleTree(rules: RuleNode, values: ReadonlyMap<string, number>, state?: RuleTreeState): {
+    weights: TargetWeights;
+    state: RuleTreeState;
+};
 
-declare function computeMetrics(series: DailyBar[], trades: Trade[], options?: MetricsOptions): MetricsResult;
+/**
+ * Resolves each {@link TacticalFeatureSpec} in `specs` to a scalar value as of
+ * date `t` by calling into `runtime` and reading the series at the appropriate
+ * bar index. All specs are computed in parallel via `Promise.all`.
+ *
+ * The returned map uses each spec's `id` as the key. The value is `undefined`
+ * when the indicator series has no data on or before `t`, or when the `delay`
+ * offset steps past the beginning of the series.
+ *
+ * Validation performed before dispatching to the runtime:
+ * - Duplicate `id` values in `specs` throw immediately.
+ * - A non-integer or negative `delay` throws immediately.
+ *
+ * @param specs   - Ordered list of feature declarations from {@link TacticalSpec.features}.
+ * @param runtime - Feature computation backend that owns the data feed and cache.
+ * @param t       - Evaluation date; the series is read at the latest bar on or before `t`.
+ * @returns A map from feature id to resolved numeric value (`undefined` when unavailable).
+ *
+ * @example
+ * ```ts
+ * import { evaluateFeatureSpecs } from '@livefolio/sdk';
+ * import type { TacticalFeatureSpec } from '@livefolio/sdk';
+ *
+ * const specs: TacticalFeatureSpec[] = [
+ *   { id: 'spy_sma200', kind: 'sma', asset: { id: 'SPY', symbol: 'SPY' }, period: 200 },
+ *   { id: 'spy_price',  kind: 'price', asset: { id: 'SPY', symbol: 'SPY' } },
+ * ];
+ *
+ * const values = await evaluateFeatureSpecs(specs, runtime, new Date('2024-06-01'));
+ * // values.get('spy_price') → 528.3
+ * ```
+ */
+declare function evaluateFeatureSpecs(specs: ReadonlyArray<TacticalFeatureSpec>, runtime: FeatureRuntime, t: Date): Promise<Map<string, number | undefined>>;
 
-declare function sharpe(returns: number[], rfAnnual: number): number;
-declare function sortino(returns: number[], rfAnnual: number): number;
+/**
+ * Wraps a {@link DataFeed} so that requests for any asset whose `id` appears in
+ * `synthetics` are intercepted and their bar stream is derived on-the-fly from
+ * the corresponding `underlying` asset.
+ *
+ * The synthesized close price on each bar is computed as:
+ * ```
+ * close_t = close_{t-1} × (1 + leverage × underlyingReturn_t) × (1 − expense/252)
+ * ```
+ * The first bar in the stream uses the underlying close directly. OHLC fields
+ * other than `close` are all set to the synthesized close (they are not
+ * 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.
+ *
+ * Throws at construction time if `synthetics` contains duplicate `id` values.
+ *
+ * @param dataFeed   - The real data feed to wrap.
+ * @param synthetics - Synthetic asset definitions; typically `spec.synthetics ?? []`.
+ * @returns A new {@link DataFeed} that intercepts synthetic asset ids.
+ *
+ * @example
+ * ```ts
+ * import { withSynthetics } from '@livefolio/sdk';
+ * import type { SyntheticAsset } from '@livefolio/sdk';
+ *
+ * const leveraged: SyntheticAsset = {
+ *   id: 'SPY_3X', symbol: 'SPY3X',
+ *   underlying: { id: 'SPY', symbol: 'SPY' },
+ *   leverage: 3,
+ *   expense: 0.01,
+ * };
+ *
+ * const feed = withSynthetics(realFeed, [leveraged]);
+ * // Requesting bars for asset { id: 'SPY_3X', ... } now returns 3× leveraged returns.
+ * ```
+ */
+declare function withSynthetics(dataFeed: DataFeed, synthetics: ReadonlyArray<SyntheticAsset>): DataFeed;
 
-declare function computeDrawdownTable(series: DailyBar[], topN: number): DrawdownEntry[];
+/** Test-only: reset the once-per-process deprecation gate. */
+declare function _resetTacticalDeprecationWarningForTesting(): void;
+/**
+ * The feature bundle computed on each rebalance step and passed to the rule
+ * tree. Produced by the `features` method of the {@link Strategy} returned by
+ * {@link fromSpec}.
+ *
+ * - `values` — named indicator results keyed by the `id` field of each
+ *   {@link TacticalFeatureSpec}. A value is `undefined` when the indicator
+ *   cannot be computed for that bar (e.g. insufficient history).
+ * - `prices` — most-recent closing prices for each asset in the universe,
+ *   keyed by asset ID.
+ */
+type TacticalFeatures = {
+    values: ReadonlyMap<string, number | undefined>;
+    prices: ReadonlyMap<AssetId, number>;
+};
+/**
+ * Runtime dependencies required by {@link fromSpec} to hydrate a
+ * {@link TacticalSpec} into a runnable {@link Strategy}.
+ */
+type FromSpecOptions = {
+    /** Feature computation backend — wraps the data feed and caching layer. */
+    runtime: FeatureRuntime;
+    /** Exchange calendar used to gate rebalance days via {@link isRebalanceDay}. */
+    calendar: Calendar;
+};
+/**
+ * Returns a stable string key that identifies the rebalance period containing
+ * date `t` for the given `freq`. Two dates that map to the same key belong to
+ * the same period and therefore produce the same rebalance decision. Used
+ * internally by {@link isRebalanceDay} to detect period boundaries.
+ *
+ * @param t    - The date to classify.
+ * @param freq - Rebalance cadence (see {@link RebalanceFrequency}).
+ * @returns A compact string such as `'2024-3'` (monthly), `'2024-W14'`
+ *   (weekly), or `'2024-1'` (quarterly Q2).
+ */
+declare function periodKey(t: Date, freq: RebalanceFrequency): string;
+/**
+ * Returns `true` when `t` is the last trading day of its rebalance period
+ * according to `freq` and `calendar`. The check is: `periodKey(t) !== periodKey(next(t))`.
+ * For `'Daily'` cadence this always returns `true`.
+ *
+ * @param t        - Current trading day (must itself be a trading day).
+ * @param freq     - Rebalance cadence (see {@link RebalanceFrequency}).
+ * @param calendar - Exchange calendar used to find the next trading day.
+ * @returns `true` if today is the last day of its period and orders should be issued.
+ */
+declare function isRebalanceDay(t: Date, freq: RebalanceFrequency, calendar: Calendar): boolean;
+/**
+ * Hydrates a plain {@link TacticalSpec} data object into a runnable
+ * {@link Strategy} that `runBacktest` can drive step-by-step.
+ *
+ * State is threaded explicitly through `build` via the
+ * {@link Strategy | `Strategy<F, S>.build`} signature. `initialState()` returns
+ * an empty {@link RuleTreeState} Map; the runtime is responsible for storing and
+ * forwarding the state between calls. This design makes `build` a pure function
+ * of its inputs — calling it twice with identical arguments produces identical
+ * outputs, enabling snapshot/restore for preview-builds in live mode.
+ *
+ * Validation performed at construction time:
+ * - A `'tactical/v0'` `kind` emits a one-time deprecation warning to `console.warn`.
+ * - Synthetic assets are checked for self-reference, symbol collisions, and
+ *   missing universe entries (see internal `validateSynthetics`).
+ *
+ * @param spec - The declarative strategy spec.
+ * @param opts - Runtime dependencies (feature backend and calendar).
+ * @returns A {@link Strategy} whose `features` method fetches indicator values
+ *   and whose `build` method converts them to rebalance orders.
+ *
+ * @example
+ * ```ts
+ * import { fromSpec, MemoryFeatureCache, NYSEExchangeCalendar } from '@livefolio/sdk';
+ * import { FeatureRuntime } from '@livefolio/sdk/features';
+ *
+ * const calendar = new NYSEExchangeCalendar();
+ * const cache    = new MemoryFeatureCache();
+ * const runtime  = new FeatureRuntime({ feed: myDataFeed, cache });
+ *
+ * const strategy = fromSpec(mySpec, { runtime, calendar });
+ * ```
+ */
+declare function fromSpec(spec: TacticalSpec, opts: FromSpecOptions): Strategy<TacticalFeatures, RuleTreeState>;
 
-interface MonthlyReturn {
-    year: number;
-    month: number;
-    return: number;
-    partial: boolean;
+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;
+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_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, 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_withSynthetics as withSynthetics };
 }
-interface YearlyReturn {
-    year: number;
-    return: number;
-    partial: boolean;
+
+/**
+ * Computes a Simple Moving Average (SMA) over a price series.
+ *
+ * Math definition:
+ * ```
+ * SMA[i] = (series[i] + series[i-1] + ... + series[i-period+1]) / period
+ * ```
+ *
+ * Warmup: the first output point corresponds to index `period - 1` in the input.
+ * Inputs `series[0]` through `series[period - 2]` have no SMA value and are
+ * excluded from the output entirely (no `undefined` placeholders; the output
+ * array is shorter than the input).
+ *
+ * Edge cases:
+ * - `period <= 0` — throws `Error`.
+ * - `series.length < period` — returns `[]` (not enough data for even one window).
+ * - `series.length === period` — returns a single-point `Series`.
+ *
+ * @param series - Input price series sorted in ascending timestamp order.
+ * @param period - Window size in bars. Must be a positive integer.
+ * @returns A `Series` of length `max(0, series.length - period + 1)`. Each point's
+ *   timestamp `t` is taken from the last bar in its window (`series[i + period - 1]`).
+ *
+ * @example
+ * ```ts
+ * import { sma } from '@livefolio/sdk';
+ *
+ * const prices = [
+ *   { t: new Date('2023-01-02'), v: 100 },
+ *   { t: new Date('2023-01-03'), v: 110 },
+ *   { t: new Date('2023-01-04'), v: 120 },
+ *   { t: new Date('2023-01-05'), v: 130 },
+ * ];
+ *
+ * const result = sma(prices, 3);
+ * // result.length === 2
+ * // result[0] => { t: new Date('2023-01-04'), v: 110 }  // (100+110+120)/3
+ * // result[1] => { t: new Date('2023-01-05'), v: 120 }  // (110+120+130)/3
+ * ```
+ */
+declare function sma(series: Series, period: number): Series;
+
+/**
+ * Computes an Exponential Moving Average (EMA) over a price series.
+ *
+ * Math definition:
+ * ```
+ * k   = 2 / (period + 1)          // smoothing factor
+ * EMA[0] = SMA(series[0..period-1])  // seeded from simple average
+ * EMA[i] = series[i] * k + EMA[i-1] * (1 - k)
+ * ```
+ *
+ * Warmup: the first `period - 1` input bars are consumed to seed the SMA
+ * initial value. The first EMA output point corresponds to input index
+ * `period - 1`; subsequent points are computed from the recursive formula.
+ * The output array is shorter than the input (no `undefined` placeholders).
+ *
+ * Edge cases:
+ * - `period <= 0` — throws `Error`.
+ * - `series.length < period` — returns `[]` (not enough data to seed the EMA).
+ * - `series.length === period` — returns a single-point `Series` equal to the
+ *   simple average of all input values.
+ *
+ * @param series - Input price series sorted in ascending timestamp order.
+ * @param period - Lookback window in bars. Must be a positive integer. Controls
+ *   the smoothing factor `k = 2 / (period + 1)`: smaller periods react faster
+ *   to recent prices.
+ * @returns A `Series` of length `max(0, series.length - period + 1)`. Each
+ *   point's timestamp `t` is taken from the corresponding input bar.
+ *
+ * @example
+ * ```ts
+ * import { ema } from '@livefolio/sdk';
+ *
+ * const prices = [
+ *   { t: new Date('2023-01-02'), v: 100 },
+ *   { t: new Date('2023-01-03'), v: 110 },
+ *   { t: new Date('2023-01-04'), v: 120 },
+ *   { t: new Date('2023-01-05'), v: 130 },
+ * ];
+ *
+ * const result = ema(prices, 3);
+ * // result.length === 2
+ * // result[0] => { t: new Date('2023-01-04'), v: 110 }  // SMA seed: (100+110+120)/3
+ * // result[1] => { t: new Date('2023-01-05'), v: ~116.7 } // EMA: 130*0.5 + 110*0.5
+ * ```
+ */
+declare function ema(series: Series, period: number): Series;
+
+/**
+ * Computes the Relative Strength Index (RSI) using Wilder's smoothing method.
+ *
+ * Math definition:
+ * ```
+ * changes[i] = series[i] - series[i-1]
+ *
+ * // Seed from simple averages of the first `period` changes:
+ * avgGain[0] = mean(max(changes[0..period-1], 0))
+ * avgLoss[0] = mean(max(-changes[0..period-1], 0))
+ *
+ * // Wilder's smoothing for subsequent periods:
+ * avgGain[i] = (avgGain[i-1] * (period-1) + gain[i]) / period
+ * avgLoss[i] = (avgLoss[i-1] * (period-1) + loss[i]) / period
+ *
+ * RS[i]  = avgGain[i] / avgLoss[i]
+ * RSI[i] = 100 - 100 / (1 + RS[i])
+ * ```
+ *
+ * Special case: when `avgLoss === 0`, RSI is clamped to 100 (infinite RS means
+ * no losing periods in the window).
+ *
+ * Warmup: requires `period + 1` input bars to produce the first RSI value
+ * (one extra bar for the initial change calculation). The first output point
+ * corresponds to input index `period`. The output array is shorter than the
+ * input (no `undefined` placeholders).
+ *
+ * Edge cases:
+ * - `period <= 0` — throws `Error`.
+ * - `series.length < period + 1` — returns `[]`.
+ * - Flat price series (all changes = 0) — returns RSI values of 100 because
+ *   `avgLoss` stays 0.
+ *
+ * @param series - Input price series sorted in ascending timestamp order.
+ * @param period - Lookback window in bars for Wilder's smoothing. Must be a
+ *   positive integer; 14 is the conventional default.
+ * @returns A `Series` of length `max(0, series.length - period)`. Each point's
+ *   timestamp `t` is taken from the corresponding input bar. Values are in
+ *   the range `[0, 100]`.
+ *
+ * @example
+ * ```ts
+ * import { rsi } from '@livefolio/sdk';
+ *
+ * // Minimal example: 5 bars, period 3 → 2 RSI values
+ * const prices = [
+ *   { t: new Date('2023-01-02'), v: 100 },
+ *   { t: new Date('2023-01-03'), v: 102 },
+ *   { t: new Date('2023-01-04'), v: 101 },
+ *   { t: new Date('2023-01-05'), v: 105 },
+ *   { t: new Date('2023-01-06'), v: 104 },
+ * ];
+ *
+ * const result = rsi(prices, 3);
+ * // result.length === 2
+ * // result[0].t => new Date('2023-01-05')
+ * // result[1].t => new Date('2023-01-06')
+ * // values are in [0, 100]
+ * ```
+ */
+declare function rsi(series: Series, period: number): Series;
+
+/**
+ * Computes a rolling historical volatility as the population standard deviation
+ * of daily log-like returns over a sliding window.
+ *
+ * Math definition:
+ * ```
+ * dailyReturn[i] = series[i] / series[i-1] - 1   // simple period return
+ *
+ * // For each window of `period` daily returns ending at index i:
+ * mean     = Σ dailyReturn[i..i-period+1] / period
+ * variance = Σ (dailyReturn[j] - mean)² / period   // population variance
+ * vol[i]   = sqrt(variance)
+ * ```
+ *
+ * The result is the per-bar standard deviation expressed as a fraction (e.g.
+ * `0.012` ≈ 1.2 % daily volatility). To annualise, multiply by `sqrt(252)` for
+ * daily bars.
+ *
+ * Warmup: requires `period + 1` price bars to produce the first volatility value:
+ * one extra bar to compute the first daily return, then `period` returns for the
+ * first window. The first output point corresponds to the `period`-th daily-return
+ * index. The output array is shorter than the input (no `undefined` placeholders).
+ *
+ * Edge cases:
+ * - `period <= 0` — throws `Error`.
+ * - `series.length < period + 1` — returns `[]`.
+ * - Flat price series (all returns = 0) — returns volatility values of `0`.
+ *
+ * @param series - Input price series sorted in ascending timestamp order. Values
+ *   must be positive (non-zero); zero prices produce `NaN` daily returns.
+ * @param period - Window size in daily-return bars. Must be a positive integer;
+ *   common values are 20 (≈ 1 month) or 252 (1 year) for daily data.
+ * @returns A `Series` of length `max(0, series.length - period)`. Each point's
+ *   timestamp `t` is taken from the last daily-return bar in its window.
+ *
+ * @example
+ * ```ts
+ * import { volatility } from '@livefolio/sdk';
+ *
+ * // 5 price bars → 4 daily returns → 1 vol point (period=4)
+ * const prices = [
+ *   { t: new Date('2023-01-02'), v: 100 },
+ *   { t: new Date('2023-01-03'), v: 101 },
+ *   { t: new Date('2023-01-04'), v: 99  },
+ *   { t: new Date('2023-01-05'), v: 102 },
+ *   { t: new Date('2023-01-06'), v: 100 },
+ * ];
+ *
+ * const vol = volatility(prices, 4);
+ * // vol.length === 1
+ * // vol[0].t => new Date('2023-01-06')
+ * // vol[0].v => population std-dev of the 4 daily returns (≈ 0.012)
+ * ```
+ */
+declare function volatility(series: Series, period: number): Series;
+
+/**
+ * Computes the rolling drawdown relative to the period high for each bar.
+ *
+ * Math definition:
+ * ```
+ * rollingMax[i] = max(series[i-period+1], ..., series[i])
+ * drawdown[i]   = (series[i] - rollingMax[i]) / rollingMax[i]
+ * ```
+ *
+ * The result is a non-positive fraction (e.g. `-0.15` means the current price
+ * is 15 % below the period high). A value of `0` means the current price equals
+ * the rolling maximum — i.e. the asset is at a new high within the window.
+ *
+ * Warmup: the first output point corresponds to input index `period - 1` (the
+ * first complete window). The output array is shorter than the input by
+ * `period - 1` points (no `undefined` placeholders).
+ *
+ * Edge cases:
+ * - `period <= 0` — throws `Error`.
+ * - `series.length < period` — returns `[]`.
+ * - All prices in a window are equal — returns `0` (current equals max).
+ * - Zero prices in the window — produces `NaN` (division by zero); callers
+ *   should guard against zero-price series.
+ *
+ * @param series - Input price series sorted in ascending timestamp order. Values
+ *   should be positive (non-zero) to avoid `NaN` results.
+ * @param period - Rolling window size in bars. Must be a positive integer.
+ *   A value of `1` always returns `0` (current equals one-bar max).
+ * @returns A `Series` of length `max(0, series.length - period + 1)`. Each
+ *   point's timestamp `t` is taken from `series[i]` (the last bar in its window).
+ *   Values are in the range `(-∞, 0]` but in practice within `[-1, 0]` for
+ *   positive price series.
+ *
+ * @example
+ * ```ts
+ * import { drawdown } from '@livefolio/sdk';
+ *
+ * const prices = [
+ *   { t: new Date('2023-01-02'), v: 100 },
+ *   { t: new Date('2023-01-03'), v: 105 },
+ *   { t: new Date('2023-01-04'), v: 95  },
+ *   { t: new Date('2023-01-05'), v: 98  },
+ * ];
+ *
+ * const dd = drawdown(prices, 3);
+ * // dd.length === 2
+ * // dd[0].t => new Date('2023-01-04'), dd[0].v => (95-105)/105 ≈ -0.095
+ * // dd[1].t => new Date('2023-01-05'), dd[1].v => (98-105)/105 ≈ -0.067
+ * ```
+ */
+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;
+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 };
 }
-declare function monthlyReturns(series: DailyBar[]): MonthlyReturn[];
-declare function yearlyReturns(series: DailyBar[]): YearlyReturn[];
 
-export { AllocationHandle, type Comparison, type DailyBar, type DateRange, type DrawdownEntry, IndicatorHandle, type IndicatorIdentity, type IndicatorType, type LiveEvaluator, type LivePreviewState, type LiveRuleState, type LiveSignalState, type LivefolioClient, type LivefolioClientOptions, type MarketProvider, type MetricsOptions, type MetricsResult, type MonthlyReturn, type MonthlyReturnsTable, PortfolioHandle, type PortfolioSnapshot, type PriceStream, SignalHandle, type SignalIdentity, type SimulateOptions, SimulationHandle, type StorageProvider, type StrategyBar, type StrategyDefinition, StrategyHandle, type StrategyLiveState, type StrategyOptions, type StrategyReferenceData, type StrategyRule, type StrategyRuleDefinition, type StrategySeriesEntry, type StreamStatus, TickerHandle, type Trade, type TradingFreq, type Unit, type YearlyReturn, allocationsEqual, computeDrawdownTable, computeMetrics, monthlyReturns as computeMonthlyReturns, computeRebalanceDates, sharpe as computeSharpe, sortino as computeSortino, yearlyReturns as computeYearlyReturns, createClient };
+/**
+ * Applies a batch of confirmed fills to a portfolio, returning a new
+ * {@link Portfolio} snapshot. This is the single function that advances
+ * portfolio state after order execution.
+ *
+ * For each fill the corresponding order is looked up in `orders` by
+ * `fill.orderRef`. The order's `kind` determines the accounting treatment:
+ * - `'open'`      — adds a new {@link Position} and debits cash.
+ * - `'close'`     — removes shares from an existing position and credits cash.
+ * - `'adjust'`    — updates the position's `quantity`; only fees are debited.
+ * - `'rebalance'` — buys or sells shares in the long position for `asset`;
+ *                   creates or removes the position as needed.
+ *
+ * The returned `portfolio.t` is updated to the maximum fill timestamp.
+ *
+ * @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`.
+ * @param orders    - The full order batch that was submitted. Used to look up
+ *   order details for each fill.
+ * @returns A new {@link Portfolio} with updated positions, cash, and timestamp.
+ *   The input `portfolio` is not mutated.
+ *
+ * @example
+ * ```ts
+ * import { applyFills } from '@livefolio/sdk';
+ * import type { Portfolio, Order, Fill } from '@livefolio/sdk';
+ *
+ * const portfolio: Portfolio = { cash: 10_000, positions: [], t: new Date('2024-01-01') };
+ *
+ * const order: Order = {
+ *   id: 'ord_1', kind: 'open',
+ *   asset: { kind: 'equity', id: 'AAPL', symbol: 'AAPL' },
+ *   side: 'long', quantity: 10,
+ * };
+ * const fill: Fill = { orderRef: 'ord_1', t: new Date('2024-01-02'), quantity: 10, price: 185, fees: 0 };
+ *
+ * const next = applyFills(portfolio, [fill], [order]);
+ * // next.cash === 8_250, next.positions.length === 1
+ * ```
+ */
+declare function applyFills(portfolio: Portfolio, fills: ReadonlyArray<Fill>, orders: ReadonlyArray<Order>): Portfolio;
+/**
+ * Projects a portfolio forward through a set of pending (unfilled) orders,
+ * returning a structurally updated snapshot. Used by strategy build helpers
+ * to read the expected post-step state before fills arrive.
+ *
+ * **v0.4 contract — structural projection only.** Quantities are updated
+ * exactly as the orders specify, but:
+ * - `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.
+ *
+ * Use {@link applyFills} (not this function) to settle the portfolio after
+ * confirmed execution.
+ *
+ * @param portfolio - The current portfolio state to project from.
+ * @param orders    - The pending orders to apply structurally. Order must have
+ *   a valid `id` and `kind`; price fields are ignored.
+ * @returns A new {@link Portfolio} with positions reflecting the orders.
+ *   `cash` and `t` are copied unchanged from `portfolio`.
+ *
+ * @example
+ * ```ts
+ * import { applyOrders } from '@livefolio/sdk';
+ * import type { Portfolio, Order } from '@livefolio/sdk';
+ *
+ * const portfolio: Portfolio = { cash: 10_000, positions: [], t: new Date('2024-01-01') };
+ *
+ * const order: Order = {
+ *   id: 'ord_1', kind: 'open',
+ *   asset: { kind: 'equity', id: 'AAPL', symbol: 'AAPL' },
+ *   side: 'long', quantity: 10,
+ * };
+ *
+ * const projected = applyOrders(portfolio, [order]);
+ * // projected.positions.length === 1, projected.cash === 10_000 (unchanged)
+ * ```
+ */
+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 RebalanceConfig, type RebalanceFrequency, type RebalanceOrder, type ReturnMode, RoutingDataFeed, RoutingDataFeedError, type RoutingDataFeedRouteFn, type RoutingDataFeedRouteMap, 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, 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, withSynthetics };