# Backtest Engine Capability Roadmap

This document tracks the production backtest capabilities implemented in
`fidc-backtest-engine` and the remaining extension points. Names and concepts
below use the platform's own engine vocabulary only.

## Scope

The roadmap focuses on making the engine complete enough for editable platform
strategies, long-range A-share backtests, futures strategies, intraday order
simulation, AI-generated strategy code, and service-level result downloads.

## Re-Audit Findings (2026-04-24)

The latest re-audit focused on the engine's execution model, account model,
order lifecycle, data helper surface, analyzer output, extension hooks, and
futures path. Confirmed aligned areas:

- Stock explicit order APIs, target order APIs, lot sizing, algo order styles,
  pending limit orders, cancellation, open order views, and final order lookup.
- Stock account and portfolio runtime fields including cash, frozen cash, total
  value, transaction cost, trading/position PnL, management fees, financing
  liability, deposit/withdraw, and position aliases.
- Scheduler, dynamic universe, subscription guard, `history_bars`,
  `current_snapshot`, `get_price`, instruments, trading-date APIs, suspension
  and ST helpers.
- Stock matching modes, slippage models, price/volume/liquidity limits, open
  auction handling, and partial fill handling in the stock broker path.
- Standalone futures account, long/short position model, open/close,
  close-today/close-yesterday, daily mark-to-market settlement, expiration
  settlement, and runtime account views.

## Capability Matrix

| Priority | Capability | Current engine state | Next implementation |
| --- | --- | --- | --- |
| P0 | Futures intraday matching | Closed for daily/open/close, tick-price futures fills, and true multi-level order-book sweeping when optional `order_book_depth` data exists. L1-only data still uses the existing L1 matcher and is not inflated into fake depth. | Extend depth fields only if production vendors expose more levels or exchange-specific fields. |
| P0 | Futures open-order lifecycle | Closed for futures pending limit orders, cross-day rematching, cancellation by id/symbol/all, and merged open-order runtime views. | Add more order status transitions only if UI requires extra intermediate event names. |
| P0 | Combined multi-account NAV | Closed. `DailyEquityPoint`, progress events, and metrics use aggregate stock + futures initial cash and total equity. | None. |
| P1 | Futures trading parameter data source | Closed for engine-side trading-parameter ingestion/resolution via `futures_trading_parameters.csv` or component data. | Add more exchange metadata columns only when source data exposes them. |
| P1 | Futures transaction cost decider | Closed. `FuturesTransactionCostModel` calculates by-money/by-volume open/close/close-today costs from trading parameters. | None. |
| P1 | Futures settlement price mode | Closed. Engine supports configurable settlement price mode and resolves settlement/prev-settlement from factor fields with close/prev_close fallback. | Add dedicated settlement columns if the storage layer later separates them from factors. |
| P1 | Frontend risk validators for futures | Closed for zero quantity, invalid limit price, active-contract, trading-phase, tick-aligned limit price, price-limit, self-trade crossing risk, paused/no executable price, margin, and close-position rejection diagnostics. | Add more exchange metadata columns only when source data exposes them. |
| P2 | Advanced data helper APIs | Closed for the engine-native data model. `DataSet` and `StrategyContext` expose dividends, splits, yield curves, generic factors, margin lists, securities margin, shares, turnover, price change, industry code, stock-connect, fundamentals, financials, point-in-time financials, current performance, dominant future, and dominant future price helpers. | Add string factor support only if source data exposes non-numeric categories. |
| P2 | Analyzer/report output | Closed for normalized trades, positions, monthly returns, risk summary, equity curve, benchmark series, metrics, and JSON report bundle via `BacktestResult::analyzer_report(_json)`. | UI/service download endpoints can serialize this report directly. |
| P3 | Mod/config/plugin architecture | Closed for a lightweight engine-native model: `BacktestProcessMod`, `BacktestProcessModLoader`, enabled-name installation, and event-bus lifecycle hooks. | Add concrete production mods/toggles as requirements appear. |

## Closed Work Items

- [x] Target-shares explicit order primitive.
- [x] Batch target-portfolio and smart target-portfolio order semantics.
- [x] Rich explicit order styles exposed to platform scripts.
- [x] Minute-level `time_rule` semantics including market-open, market-close,
      and physical-time style schedules.
- [x] Fine-grained daily, minute, and tick strategy execution entrypoints.
- [x] Scheduled actions evaluated against explicit intraday times.
- [x] `update_universe`, `subscribe`, and `unsubscribe`.
- [x] Tick-frequency subscription guards at strategy API level.
- [x] VWAP and TWAP explicit action styles.
- [x] `order_target_portfolio_smart(..., order_prices=AlgoOrder, valuation_prices=...)`.
- [x] Trading PnL, position PnL, dividend receivable, and richer position
      lifecycle fields.
- [x] Stock position aliases including `order_book_id`, `avg_price`,
      `sellable`, `closable`, `equity`, and `position_prev_close`.
- [x] `history_bars` numeric helper for daily, intraday, and tick fields.
- [x] `current_snapshot`, instrument metadata, all-instrument queries, and
      active/historical instrument helpers.
- [x] Trading-date range, previous-date, and next-date helpers.
- [x] Phase-aware minute/tick history cursor semantics matching the active bar
      or tick callback.
- [x] Suspension, ST, date-range price, active instrument, and instrument
      history helpers.
- [x] Open-order status, unfilled quantity, final order lookup, average fill
      price, and transaction cost aggregation.
- [x] Stock-account runtime view and account map/accessor surface.
- [x] Deposit/withdraw, financing liability, repay, management-fee rate, and
      management-fee callback support.
- [x] Standalone futures account, futures order execution, futures events, and
      futures runtime views.
- [x] Futures order intents wired into the generic engine loop.
- [x] Futures expiration settlement and data-driven expiration schedule.
- [x] Futures intraday matching, pending order lifecycle, cancellation, and
      aggregate multi-account metrics.
- [x] Futures trading-parameter resolver, cost resolver, margin resolver,
      settlement resolver, and submission validators.
- [x] Optional true multi-level futures order-book depth data and sweep matching.
- [x] Dividends, splits, yield curves, generic factors, margin lists, securities
      margin, shares, turnover, price change, stock-connect, industry code,
      fundamentals, financials, point-in-time financials, current performance,
      dominant future, and dominant future price helpers.
- [x] Normalized trades, positions, benchmark, monthly returns, risk summary,
      equity curve, metrics, and downloadable analyzer bundle.
- [x] Event-bus process listeners and installable process mods.

## Current Step

P0-P2 capability gaps are closed in the engine core. P3 has a lightweight
event-driven extension loader. Remaining work should be driven by concrete
production strategy or UI requirements: optional vendor-specific depth fields,
additional exchange metadata columns, string-valued factor categories, and
service/UI download wiring.