topstep-backtest 0.1.0__tar.gz

topstep_backtest-0.1.0/.gitignore

@@ -0,0 +1,43 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+*.so
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# uv
+.uv/
+uv.lock
+
+# Testing / coverage
+.pytest_cache/
+.coverage
+coverage.xml
+htmlcov/
+.ruff_cache/
+.mypy_cache/
+.pyright/
+
+# Docs
+site/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+.DS_Store
+
+# Secrets / local config
+.env
+.env.*
+!.env.example
+
+# Hypothesis
+.hypothesis/

topstep_backtest-0.1.0/AGENTS.md

@@ -0,0 +1,216 @@
+# topstep-backtest — agent guide
+
+Dense reference for working on this codebase. Read this before touching code.
+Companion docs: `docs/DESIGN.md` (architecture contract), `docs/topstep-rules.md`
+(rulebook with sources + verify-checklist), `docs/ROADMAP.md` (phase gates).
+
+## What this is
+
+An event-driven backtester answering ONE question: *can a strategy profitably pass
+the Topstep Trading Combine?* Two load-bearing properties:
+
+1. **Backtest/live parity** with the sibling `topstep-sdk` (`../topstep-sdk`, an
+   editable uv path dep): strategies are written once against structural protocols
+   that BOTH `SimBroker` and `AsyncTopstepClient` satisfy. The SDK's msgspec models
+   (`OrderModel`, `HalfTradeModel`, `PositionModel`, enums, `APIError`) are imported
+   verbatim — never redefined.
+2. **The prop-firm rule engine is real-time**, not a post-hoc scorecard: the
+   two-state trailing MLL, optional DLL, consistency target, position caps, and the
+   16:10 ET flatten all mutate the trade sequence (forced liquidation with adverse
+   slippage + Topstep's $10/contract auto-liquidation fee).
+
+**Scope:** Combine only. Funded/XFA is parked (docs/topstep-rules.md §6). Tier-0
+(OHLCV bars) fills only, so far.
+
+## Binding conventions (violations are bugs)
+
+- **Money:** `Decimal` on the tick grid, always. All grid math via `core/money.py`.
+  Position accounting is FIFO lots with an exact cost basis — unrealized P&L goes
+  through `position_unrealized` (division-free); never average-then-divide.
+  *Indicator values are the deliberate exception:* TA-Lib computes in float64 and the
+  `Decimal` handed back at the boundary is **not** tick-snapped — an indicator level is
+  not a tradeable price, and quantizing it to the grid would be a lie. Never route an
+  indicator value into grid math without an explicit `round_to_tick`.
+- **Time:** int-ns UTC in the hot path; canonical timezone **ET** at boundaries
+  (flatten 16:10, session close 17:00, day reset 18:00 ET). All time flows through
+  the `Clock` protocol — never `datetime.now()`. `dt_to_ns`/`ns_to_dt` are exact
+  integer math (no float round-trips).
+- **No look-ahead, structurally:** bars stamp `ts_init` at CLOSE; an order
+  participates in a bar only if `accepted_ts <= bar.ts_event` (its OPEN); trailing
+  stops ratchet only from bars the order lived through; `SimHistoryApi` serves only
+  already-seen bars; the engine asserts feed time-order.
+- **Intrabar determinism:** fills and rule breaches are ordered along ONE
+  pessimistic price path (`fills/path.py`; adverse extreme first) by TRIGGER level
+  (never slippage-adjusted prices); breach ties beat fills; equity is re-checked AT
+  each fill after it applies.
+- **Rejections:** always the SDK's `APIError` with the gateway's numeric
+  `error_code` (see `execution/rejections.py` + SDK `PLACE_ORDER_ERRORS` et al.).
+- `protocols.py` is THE canonical interface module. Change signatures there first
+  or not at all; `tests/parity/` has a pyright-strict conformance test plus a
+  signature-diff of `SimOrderApi.place` against the SDK's `OrderResource.place`
+  that catches drift. **There is no CI** — drift surfaces only when someone runs
+  `uv run pytest`. Both tests prove STRUCTURAL conformance; the BEHAVIOURAL gate
+  (an intent-sequence test asserting an identical Submit/Modify/Cancel sequence
+  sim vs live, docs/ROADMAP.md Phase 4) is not built, so behavioural parity is
+  argued, not proven.
+- Toolchain: `uv`, ruff (line 100, E/F/I/UP/B/SIM/ASYNC/RUF), pyright **strict**,
+  pytest (+ hypothesis, asyncio_mode=auto). Everything must stay green:
+  `uv run pytest && uv run ruff check . && uv run pyright`. Runtime deps are
+  `topstep-sdk`, `msgspec`, and `ta-lib` — the last is core, not an extra.
+
+## Map
+
+| Module | Owns |
+|---|---|
+| `protocols.py` | Clock/Bar/DataFeed/Broker/OrderApi/PositionApi/HistoryApi/FillModel/Fill/WorkingOrder |
+| `core/` | money (grid/P&L), instruments (15-product spec table), time (ET sessions), ids |
+| `rules/` | `CombineKernel` — THE canonical rulebook state machine (golden-fixtured); params per size |
+| `clock/` | deterministic `TestClock` (`__test__=False`!), wall-clock `LiveClock` |
+| `fills/` | pessimistic Tier-0 `BarFillModel`, shared `build_path`, `TopstepFees` (per-side stack) |
+| `data/` | wrangler (explicit `stamp="open"|"close"` — never guess), validator, synthetic generator, `ListBarFeed` |
+| `execution/` | `SimBroker` (lifecycle, OCO brackets, netting, breach walk, forced liq), rejections |
+| `engine/` | `BacktestEngine` loop + `BacktestResult` (msgspec-serializable; carries `rejections`) |
+| `strategy/` | `Strategy` base + `StrategyContext` (the write-once seam); `SymbolStrategy` (`use()` registration, ready-gate); `tracker.py` — `NetPosition`/`PositionTracker`/`OrderTracker`, pure event folds over SDK models ONLY (that is the parity argument) |
+| `metrics/` | `SummaryStats` (frozen msgspec) + `compute_summary` — drawdown, win rate, expectancy, profit factor, distance-to-floor, consistency headroom |
+| `harness.py` | `Backtest` facade (`run()`/`arun()`/`from_dataframe`, ONE shared clock, instruments derived from the feed, strict `validate_bars`, `account=`, `fee_model=`) + `Report` (verdict/day-trail/summary rendering, provenance line); refuses backtesting.py's economics knobs by name |
+| `indicators/` | TA-Lib adapter — `TalibIndicator` drives 152 of TA-Lib's 161 functions bar-by-bar (nine refused, see below); typed named wrappers (`Sma`/`Ema`/`Rsi`/`Atr`/`Macd`/`BBands`/…); pure-Python `Cross`; `Indicator`/`ValueSource` protocols in `base.py` |
+
+## Semantics that trip people up
+
+- **MLL is two-state:** floor ratchets ONLY on end-of-day closed balance (locks
+  permanently at the starting balance once EOD ≥ start + buffer); breach checks run
+  every tick on realized+unrealized. Intraday-trailing = Apex, not Topstep.
+- A session close at/below the floor is itself a breach (flatten fees can do it).
+- DLL (optional, off by default) is NOT a fail: flatten + day-lock, cleared at
+  18:00 ET; no re-emission while locked; does not preclude passing.
+- Consistency: `best_day <= 0.5 * total_profit` — the formula is canonical; the
+  dollar table is canonical (no cross-size ratio holds).
+- **There is NO exchange holiday calendar, by decision.** `core/calendar.py` was
+  deleted: its computed table disagreed with CME on about five dates a year (it
+  marked MLK / Presidents' Day / Memorial Day / Juneteenth / Labor Day as full
+  closures when CME equity index trades a half session), and the cleaner built on
+  it ran by DEFAULT, so it silently deleted tradable sessions. A wrong answer you
+  cannot see beats a missing feature, so the feature went. Consequences to hold in
+  your head: a holiday bar is indistinguishable from any other weekday bar; the
+  validator has no `holiday_bar`/`early_close_bar` code and never had a
+  replacement; `SimBroker` rejects only weekends (`error_code` 5, "market closed
+  (weekend)"); and `data/synthetic.py` skips weekends ONLY — its `days=` counts
+  WEEKDAYS, so a synthetic tape spanning Thanksgiving or Good Friday (those two
+  ARE genuine CME full closures) emits a session real data would not contain.
+  **Filter exchange holidays upstream, in the data you feed in.**
+- ALL market orders — including `positions.close`/`partial_close` — rest and fill
+  at the NEXT bar's open (Tier-0). `wait_for_fill` raises in sim: use
+  `on_order`/`on_fill` callbacks (parity-safe in both worlds).
+- Bracket children are created at the entry fill (offsets from the ACTUAL fill
+  price), active the next bar; only the TP carries `linked_order_id` (gateway
+  shape); OCO pairing lives in the broker's internal map. Reduce-only orders clamp
+  to the live position and can never flip exposure.
+- `OrderModel.trail_price` is emitted as the trail DISTANCE as a price offset
+  (matching the SDK field docs), not the absolute stop.
+- Limit fills require trade-THROUGH by default (exact touch — including at the
+  open — does not fill unless `fill_limit_on_touch=True`).
+- **Refused placements are tallied, not silent.** Every order path funnels through
+  one choke point that counts rejections by gateway `error_code`:
+  `SimBroker.rejections` (a dict) and `BacktestResult.rejections` (sorted
+  `(error_code, count)` pairs), and `Report` prints a REJECTED line when it is
+  non-empty. Before this, a strategy whose every order was refused — cap 4,
+  outside-hours 5 — rendered as a clean zero-trade report. A zero-trade result
+  with a REJECTED line is a wiring bug, not a flat strategy.
+- **TA-Lib is the single source of every indicator value.** Nothing in this repo
+  re-implements an indicator formula, so there is no second implementation to drift.
+  Values are float64 → `Decimal` at the boundary and NOT tick-snapped (see Money above);
+  float arithmetic is deterministic, so reruns stay byte-equal, but values are
+  float-precise, not Decimal-exact.
+- **Bounded history is a PARITY decision, not an optimisation.** The buffer keeps the last
+  `history_bars` bars, so a value is a pure function of that window. Unbounded history would
+  make every value depend on where the series happened to start, and a live session warming
+  up from a finite history fetch could never reproduce a backtest that began earlier.
+  **Preload `history_bars` bars live** for bit-exact parity.
+- **`ready` is NOT `warm`.** `ready` = a value EXISTS (at `lookback`). `warm` = the buffer is
+  FULL (at `history_bars`), i.e. the value no longer depends on where this run started. Bars
+  in `[lookback, history_bars)` are cold-start dependent. **Parity begins at `warm`**; the
+  `use()` ready-gate is a warmup gate, not a parity gate. `TalibLine` exposes `warm` too.
+  Never write "parity holds once ready".
+- **`history_bars` is NOT always `max(512, 64 × lookback)`.** Functions whose memory is a
+  RATE get a derived window: SAR/SAREXT from `acceleration` (`SAR()` → 2000,
+  `SAR(acceleration=0.001)` → 40000; its lookback is 2 either way), MAMA from `slowlimit`,
+  KAMA a flat 9000-bar floor. Read `history_bars` off the instance, never recompute it.
+- **"Windowed == unbounded" is NOT universal.** It holds (and is asserted) for the
+  exponentially-decaying family — EMA, Wilder RSI/ATR/ADX, MACD, DEMA/TEMA, T3, MAMA,
+  HT_TRENDLINE. It does NOT hold for accumulators (OBV, AD — weight 1.0 forever, so the LEVEL
+  is window-relative: use slope/divergence, never the level), running-sum functions (SMA and
+  what is built on it — STOCH slowd, CCI, MFI, ACCBANDS, BETA, ADOSC — within an ulp, since
+  float rounding depends on where the sum began), or adaptive smoothers (KAMA, HT_DCPERIOD).
+  **Backtest/live parity is unaffected either way** — both sides run the same window over the
+  same bars; only the "also equals an unbounded run" bonus varies.
+- Streaming == batch, **bit for bit**: TA-Lib recomputes from index 0 every call and every
+  function is causal, so `FUNC(bars[:t+1])[-1] == FUNC(bars)[t]` exactly. `update(bar)`
+  appends to a buffer of already-closed bars and reads the LAST output element — the
+  no-look-ahead invariant is structural, not a convention.
+- **Nine of the 161 functions are REFUSED at construction** (152 wrap fine): `EXP`/`COSH`/
+  `SINH`/`ACOS`/`ASIN` overflow or leave their domain at futures prices, so they could never
+  become ready — `SymbolStrategy` would swallow every bar and the strategy would silently
+  never trade (the constructor probes on a PRICE-REALISTIC series to catch this); `MAVP`
+  needs a non-bar `periods` input; `MAXINDEX`/`MININDEX`/`MINMAXINDEX` return an OFFSET into
+  the array passed in, whose basis silently changes once the bounded window fills.
+- **Lossy parameters are refused.** `Sma(14.7)` (would have become `SMA(14)`) and
+  `matype=2.9` (would have become WMA when DEMA was meant) raise `ValueError`; so do bools
+  and non-integer `history=`. `Sma(14.0)` — an integral float — is fine.
+- **`_compute` clears its dirty flag only AFTER the TA-Lib call succeeds.** Order matters and
+  is not stylistic: clearing it first MEMOISES THE FAILURE — the exception surfaces once, then
+  every later read that bar reports a benign "not ready", which `SymbolStrategy._gated()`
+  silently swallows, so a broken indicator becomes a strategy that just never trades. Never
+  reorder those two lines when refactoring `_compute`. Pinned by
+  `tests/unit/test_talib_adapter_hardening.py::test_a_raising_compute_is_not_cached_as_not_ready`.
+- **Thread-safety: build anywhere, drive anywhere; one instance per thread.** `talib`'s
+  `Function` keeps its parameters in a `threading.local`, so a Function configured on one
+  thread silently reverts to TA-Lib's DEFAULTS on another (an `Ema(50)` quietly computing
+  `Ema(30)`). The adapter therefore treats it as STATELESS — parameters re-passed on every
+  call, `price=` applied by choosing which bar field fills the input slot instead of mutating
+  `input_names`. Keep it that way: never stash config on the Function. A single instance is
+  still not safe to drive from two threads at once (per-bar state) — parameter sweeps get one
+  instance per worker.
+- **`STDDEV`/`VAR`/`BBANDS` use TA-Lib's naive `E[x²] − E[x]²`**, which cancels at index price
+  levels: measured relative error 1.9e-9 @5k, 2.4e-8 @20k, 6.7e-7 @100k. Fine for a threshold
+  read; a `Cross` on a Bollinger edge can flip on that noise. A band touch is not exact.
+- **`Rsi` on flat closes reads 0, not 100.** TA-Lib returns 0.0 when all closes are equal
+  (all-gains still reads 100, all-losses 0). The old native "zero avg loss reads 100" rule
+  is gone; TA-Lib is the authority.
+- **Minimum periods are per-function**, not global: TA-Lib rejects `RSI(1)`, `STDDEV(1)`,
+  `MAX(1)`, `MIN(1)`, `ADX(1)` (need ≥2) while `SMA(1)`, `EMA(1)`, `ATR(1)`, `WMA(1)` are
+  fine. The adapter PROBES TA-Lib at construction rather than hard-coding a table that
+  would drift → `ValueError("TA-Lib rejected …")` at `Rsi(1)`, not 500 bars into a run.
+  `period < 1` still raises `ValueError("period must be >= 1, got N")`. Lookbacks are
+  TA-Lib's: `Sma(3)`/`Ema(3)`/`StdDev(3)`/`Highest(3)` need 3 bars, `Rsi(3)`/`Atr(3)` need 4.
+- **`TalibLine` is not `use()`-registerable.** A line (`macd.line("macdsignal")`) has no
+  `update` on purpose, so it cannot satisfy `Indicator`; `SymbolStrategy.use()` raises
+  `ValueError` if handed one — it would never advance and would gate the strategy forever.
+  Register the OWNER; `use()` resolves a `Cross` input through `TalibLine.owner`, so
+  `use(Cross(macd.line("macd"), macd.line("macdsignal")))` works once `macd` itself is
+  `use()`d.
+- **Three more `use()` guards, each pinning a silent failure.** A `Cross` over another
+  `Cross` is refused (`ValueError`): it type-checks but has no `.value`, so it used to die
+  with `AttributeError` on the first bar both inner inputs were ready, hours in. A
+  non-`Indicator` is refused (`TypeError`) at registration, not on the first bar. And a
+  `Cross` that was never `use()`-registered now RAISES from `up`/`down` once both inputs are
+  ready — it never updates, so it used to read False forever and take zero trades in silence.
+
+## Testing idioms
+
+- Golden fixtures for every rulebook worked example (`tests/golden/`); hypothesis
+  property suites for money/kernel/fills invariants (`tests/property/`, seeded/
+  derandomized); parity conformance in `tests/parity/`; determinism =
+  `msgspec.json.encode(result)` equality across reruns.
+- Build test bars with `tests/conftest.py::minute_bar` (ET wall-clock in, exact ns
+  out). A bar "at 9:30" OPENS 9:30 and CLOSES 9:31.
+
+## Known deferred items (documented, not bugs)
+
+STOP_LIMIT + JOIN_BID/JOIN_ASK rejected at Tier-0; no MessageBus yet; no
+multi-timeframe resampling (history refuses non-native bar specs); DAY-unit
+wrangling rejected (23h Globex day needs a session-aware resampling layer); no
+exchange holiday calendar at all (removed 2026-07-28 — holidays and half sessions
+are the caller's problem, upstream, see above); no behavioural intent-sequence
+parity test (docs/ROADMAP.md Phase 4); fee/rule numbers are cited config pending
+calibration against a real account (docs/topstep-rules.md §9 checklist, correct
+fee rates with `fee_model=`).

topstep_backtest-0.1.0/CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog
+
+All notable changes to this project are documented here. This project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html). While the version is
+below 1.0, minor releases may contain breaking changes.
+
+## [0.1.0] — 2026-07-28
+
+First public release. Pre-alpha: the engine core is well tested, but the Topstep
+rule and fee constants are **not yet calibrated against a live account**, so a
+`PASSED`/`FAILED` verdict is a diagnostic, not an authoritative answer.
+
+### Added
+
+- Event-driven backtest engine with backtest/live parity against
+  [`topstep-sdk`](https://pypi.org/project/topstep-sdk/): strategies are written
+  once against structural protocols that both `SimBroker` and `AsyncTopstepClient`
+  satisfy. SDK msgspec models (`OrderModel`, `PositionModel`, `HalfTradeModel`,
+  enums, `APIError`) are imported verbatim, never redefined.
+- `CombineKernel` — the canonical Topstep Combine rulebook as a pure state
+  machine: two-state trailing MLL (floor ratchets only on end-of-day closed
+  balance, breach checked every tick on realized + unrealized equity), optional
+  daily loss limit, consistency target, position caps, 16:10 ET flatten.
+- `Backtest(bars, strategy).run()` facade plus `Report`, and a
+  backtesting.py-flavoured strategy dialect (`SymbolStrategy` with `use()`
+  indicator registration and `buy`/`sell`/`close` sugar).
+- Tier-0 fill model over OHLCV bars: market orders rest to the next bar's open,
+  limit orders require trade-through, one pessimistic intrabar price path shared
+  by fills and rule-breach detection.
+- Indicators via TA-Lib — `TalibIndicator` drives 152 of TA-Lib's 161 functions
+  bar-by-bar, with typed wrappers (`Sma`, `Ema`, `Rsi`, `Atr`, `Macd`, `BBands`, …).
+  Nothing in this package re-implements an indicator formula.
+- Exact-Decimal money on the instrument tick grid, FIFO lot cost basis, int-ns
+  UTC hot path with ET session boundaries, and a 15-product instrument table.
+- Data wrangling from OHLCV records or a pandas DataFrame with an explicit
+  `stamp="open"|"close"`, a strict validator, and a seeded synthetic generator.
+
+### Known limitations
+
+- **No exchange holiday calendar.** Bars on market holidays and past early-close
+  halts are not detected or filtered anywhere. Filter them upstream.
+- **No continuous-contract stitching.** One contract per run, inside a single
+  front-month window. A multi-month export spanning a roll is silently merged.
+- **Rule and fee constants are uncalibrated** — see `docs/topstep-rules.md` §9.
+- Multi-symbol runs, `dll_enabled=True`, and non-quarter-tick products (CL, GC)
+  are not exercised end to end.
+- Tier-0 bar fills only. No quote, depth or MBO tiers.
+
+[0.1.0]: https://pypi.org/project/topstep-backtest/0.1.0/

topstep_backtest-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tarric Sookdeo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

topstep_backtest-0.1.0/PKG-INFO

@@ -0,0 +1,250 @@
+Metadata-Version: 2.4
+Name: topstep-backtest
+Version: 0.1.0
+Summary: Event-driven backtesting framework for Topstep Trading Combine strategies, with backtest/live parity against topstep-sdk.
+Author-email: Tarric Sookdeo <tarricsookdeo@outlook.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: backtesting,combine,futures,prop-firm,topstep,trading
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: msgspec<1.0,>=0.18
+Requires-Dist: ta-lib<0.8,>=0.7.1
+Requires-Dist: topstep-sdk<0.2,>=0.1.2
+Requires-Dist: tzdata>=2024.1; sys_platform == 'win32'
+Provides-Extra: data
+Requires-Dist: pandas>=2.2; extra == 'data'
+Provides-Extra: dev
+Requires-Dist: hypothesis>=6.100; extra == 'dev'
+Requires-Dist: pandas>=2.2; extra == 'dev'
+Requires-Dist: pyright>=1.1.380; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff<0.17,>=0.16; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# topstep-backtest
+
+An event-driven backtesting framework for developing futures strategies that can
+**profitably pass the Topstep Trading Combine**.
+
+Its defining property is **backtest/live parity** with the companion
+`topstep-sdk`: a strategy is written **once** against structural protocols that
+both the deterministic `SimBroker` *and* the live `AsyncTopstepClient` satisfy.
+Its core differentiator is a first-class **prop-firm rule engine**: the two-state
+trailing Maximum Loss Limit, optional Daily Loss Limit, consistency target,
+position caps, and session flatten are enforced *in real time* (including
+intrabar forced liquidation with adverse slippage), not scored after the fact.
+
+```python
+class SmaCross(SymbolStrategy):
+    def __init__(self, contract_id: str) -> None:
+        super().__init__(contract_id)
+        self.fast = self.use(Sma(20))  # TA-Lib, driven bar by bar, causal by construction
+        self.slow = self.use(Sma(50))
+        self.cross = self.use(Cross(self.fast, self.slow))
+
+    async def on_bar(self, bar: Bar) -> None:  # gated until every use()d indicator is ready
+        if self.cross.up and self.position.flat:
+            await self.buy(  # sugar over ctx.orders — the topstep-sdk surface
+                2,
+                stop_loss_ticks=40,
+                take_profit_ticks=80,  # signed-tick OCO bracket
+            )
+```
+
+## Install
+
+```bash
+pip install topstep-backtest
+pip install "topstep-backtest[data]"   # adds pandas, for DataFrame input
+```
+
+Requires Python 3.12+. TA-Lib is a core dependency and ships wheels for common
+platforms; on others you will need the TA-Lib C library first.
+
+```python
+from datetime import date
+from decimal import Decimal
+
+from topstep_backtest import AccountSize, Backtest, SymbolStrategy
+from topstep_backtest.core.instruments import spec_for_symbol
+from topstep_backtest.data.synthetic import synthetic_bars
+from topstep_backtest.indicators import Cross, Sma
+
+MNQ = "CON.F.US.MNQ.U26"
+
+
+class SmaCross(SymbolStrategy):
+    def __init__(self, contract_id: str) -> None:
+        super().__init__(contract_id)
+        self.fast = self.use(Sma(10))
+        self.slow = self.use(Sma(30))
+        self.cross = self.use(Cross(self.fast, self.slow))
+
+    async def on_bar(self, bar) -> None:
+        if self.cross.up and self.position.flat:
+            await self.buy(1, stop_loss_ticks=40, take_profit_ticks=80)
+        elif self.cross.down and self.position.is_long:
+            await self.close()
+
+
+bars = synthetic_bars(
+    contract_id=MNQ,
+    spec=spec_for_symbol("MNQ"),
+    start_day=date(2026, 5, 4),
+    days=5,
+    seed=7,
+    start_price=Decimal("23000.00"),
+    bars_per_day=120,
+    vol_ticks=12,
+)
+print(Backtest(bars, SmaCross(MNQ), account=AccountSize.S50K).run())
+```
+
+Feeding your own data (e.g. normalized Databento candles):
+
+```python
+from topstep_backtest.data.wrangler import bars_from_dataframe
+
+bars = bars_from_dataframe(
+    df,
+    contract_id="CON.F.US.MNQ.U26",
+    spec=spec,
+    unit=AggregateBarUnit.MINUTE,
+    unit_number=1,
+    stamp="open",
+)  # declare what your timestamps mean!
+```
+
+`bars_from_records` is the same loader without the pandas dependency.
+
+## Status and limitations
+
+**Pre-alpha (0.1.0).** The engine core is well covered — exact-Decimal money on
+the tick grid, FIFO lot accounting, a structurally enforced no-look-ahead
+firewall, and byte-identical reruns — but read these before trusting a number:
+
+- **The rule and fee constants are NOT calibrated against a live account.** They
+  are researched, source-cited config (docs/topstep-rules.md §9 has 8 unchecked
+  boxes). Treat a `PASSED`/`FAILED` verdict as a diagnostic, not an answer, and
+  distrust any result landing within a tick or a fee of a limit.
+- **No exchange holiday calendar ships with this package.** Bars on market
+  holidays and past early-close halts are not detected, flagged or filtered
+  anywhere — filter them upstream. (A built-in calendar was removed in 0.1.0: it
+  disagreed with CME on several dates a year and silently discarded tradable
+  sessions, which is worse than not having one.)
+- **One contract per run, inside a single front-month window.** There is no
+  continuous-contract stitching, and no roll detector. A multi-month export
+  spanning a quarterly roll is silently merged into one price series.
+- **Tier-0 bar fills only.** Market orders fill at the next bar's open and
+  default to zero slippage, so a strategy whose edge is thinner than roughly
+  8–10 ticks per round turn is inside the model's error bars. Event windows
+  (08:30 ET releases and the like) are not honestly modelled at bar resolution.
+- **Untested end to end:** multi-symbol runs, `dll_enabled=True`, and
+  non-quarter-tick products (CL, GC).
+
+What is proven is *structural* parity — pyright-strict conformance plus a
+signature-diff test against the live SDK. The behavioural gate (an intent-sequence
+test against a recording live broker) is **not built yet**; see docs/ROADMAP.md.
+
+## What works today
+
+- **Rule kernel** (`rules/`) — the canonical Topstep Combine rulebook: EOD-ratcheting
+  trailing MLL with permanent lock at the starting balance, real-time breach on
+  realized+unrealized equity, optional DLL (flatten-and-lock, not a fail),
+  consistency (`best_day ≤ 50% × total`), fixed 5/10/15-mini position caps —
+  golden-fixtured against the documented worked examples.
+- **Deterministic engine** (`engine/`, `clock/`) — single time-ordered loop,
+  `TestClock`, strict `ts_init` ordering assertions, bit-for-bit reproducible runs.
+- **SimBroker** (`execution/`) — full order lifecycle (market/limit/stop/trailing,
+  signed-tick OCO brackets), netting + exact-Decimal P&L, gateway-parity `APIError`
+  rejections tallied on the result, intrabar fill-vs-breach resolution along one
+  pessimistic price path, forced liquidation whose loss can exceed the floor.
+- **Tier-0 fills** (`fills/`) — pessimistic bar fills: adverse-extreme-first path,
+  next-bar-open for close signals, gap-through at the open, ≥1-tick stop slippage,
+  trade-through (not touch) limit fills; per-side/per-instrument Topstep fee stack,
+  correctable via `Backtest(..., fee_model=TopstepFees(overrides={...}))`.
+- **Data layer** (`data/`) — pandas/records → validated `Bar` streams (explicit
+  open/close stamping kills the off-by-one-bar look-ahead), tick-grid validation,
+  session/halt/weekend checks, deterministic synthetic generator.
+- **Indicators** (`indicators/`) — every indicator is TA-Lib: `TalibIndicator` drives 152 of
+  its 161 functions bar-by-bar (typed `Sma`/`Ema`/`Rsi`/`Atr`/`Macd`/`BBands`/… wrappers,
+  plus a pure-Python `Cross`), so no formula is re-implemented here to drift; the nine
+  refused are the ones that could only fail silently. Streaming values are bit-identical to a
+  batch run, and the bounded history window is a *parity* decision — preload `history_bars`
+  bars live and the live number equals the sim number. Parity begins at `warm` (the window is
+  full), not at `ready` (a value exists).
+- **Parity seam** (`protocols.py`) — pyright-strict conformance tests prove
+  `AsyncTopstepClient` and `SimBroker` satisfy the same `Broker` protocol, plus a
+  signature-diff test against the live SDK that fails the suite on drift.
+
+## Development
+
+From a checkout (the sibling `topstep-sdk` repo is expected at `../topstep-sdk`;
+set `UV_NO_SOURCES=1` to resolve it from PyPI instead):
+
+```bash
+uv sync --extra dev
+uv run pytest && uv run ruff check . && uv run ruff format --check . && uv run pyright
+cd examples && uv run python run_combine.py   # end-to-end combine verdict
+```
+
+## Documentation
+
+The source repository is private, so there is no public issue tracker or docs
+site. Everything below ships **inside the sdist** — `pip download --no-binary
+:all: topstep-backtest` and unpack it, or read the copies in your environment.
+
+- **`docs/GUIDE.md` — start here**: the user guide (data in, writing strategies,
+  wiring runs, reading results, verification checklist).
+- `docs/TUTORIAL_EMA_CROSSOVER.md` — an in-depth walkthrough building one
+  strategy end to end.
+- `docs/STRATEGY_API.md` — the strategy dialect reference, including the
+  indicator surface.
+- `docs/topstep-rules.md` — the rulebook being enforced, with sources,
+  confidence levels, and a verify-before-trusting checklist.
+- `docs/DESIGN.md` — architecture contract (parity seam, no-look-ahead
+  invariants, fill tiers). Its §4 layout is the *target* architecture, not the
+  current tree.
+- `AGENTS.md` — dense maintainer/agent reference and the real module map.
+- `examples/` — runnable: `run_real_data.py` (your CSV/Parquet → verdict),
+  `run_combine.py` (synthetic end-to-end), `ema_cross.py`, `sma_cross.py`,
+  `talib_macd.py`.
+
+## Roadmap
+
+Analytics + Monte-Carlo pass-probability → live adapter + calibration → L1/L2/MBO
+fill tiers. Funded-account (XFA) modeling is deliberately parked. See
+`docs/ROADMAP.md` in the sdist.
+
+## Stack
+
+Python 3.12+ · `topstep-sdk` · `msgspec` · `TA-Lib` · `uv` · `ruff` · `pyright`
+(strict) · `pytest` + `hypothesis`. Canonical timezone: **ET** (`America/New_York`);
+internal hot path is int-ns UTC; all money is exact `Decimal` on the tick grid —
+indicator values cross from float64 into `Decimal` and are deliberately *not*
+tick-snapped (an indicator level is not a tradeable price).
+
+## License
+
+MIT — see LICENSE.
+
+> **Unofficial.** Not affiliated with, endorsed by, or sponsored by Topstep, LLC
+> or ProjectX Trading, LLC. "Topstep" is a trademark of its respective owner and
+> is used here only to identify the evaluation program this tool models. Rule
+> numbers researched July 2026 — re-verify against Topstep's help center before
+> trusting a pass verdict (see the checklist in docs/topstep-rules.md §9).
+>
+> **Not financial advice.** This software simulates a trading evaluation and can
+> be wrong. You are solely responsible for any capital you risk.