topstep-backtest 0.2.2__tar.gz → 0.3.0__tar.gz

{topstep_backtest-0.2.2 → topstep_backtest-0.3.0}/.gitignore

@@ -42,5 +42,6 @@ site/
 # Hypothesis
 .hypothesis/
 
-# Tearsheet output from examples/run_tearsheet.py (written to the CWD)
+# Tearsheet output from examples/run_tearsheet.py / run_replay.py (written to the CWD)
 tearsheet.html
+replay-tearsheet.html

{topstep_backtest-0.2.2 → topstep_backtest-0.3.0}/AGENTS.md

@@ -77,10 +77,28 @@ print(report.result.verdict.name)  # Verdict is an IntEnum — print .name
 
 `Backtest` takes an INSTANCE, never the class; `run()` is sync, `arun()` the coroutine. Engine,
 broker, kernel and strategy state are single-use — fresh `Backtest` AND fresh strategy per run.
+
+Managing a trade after entry: the bracket is two REAL reduce-only orders (a stop and a
+limit, OCO-paired) created when the entry fills, so `move_stop(ticks=0)` /
+`move_target(price=...)` amend them in flight — `ticks` is signed in the POSITION'S favour
+(`ticks=0` is breakeven either way), measured off `position.avg_price` (the venue's own
+average, `None` when flat), and both return how many orders moved with rejections routed to
+`on_reject`. They act on bracket children only (`parent_order_id` set), so a stop-ENTRY of
+your own is never mistaken for protection. An amended level is live from the NEXT bar.
+
 Real data: `Backtest.from_dataframe(df, strategy, *, contract_id, stamp, unit, unit_number)` —
 the spec is derived from `contract_id` — or build bars yourself with `bars_from_dataframe` /
 `bars_from_records`, which do take an explicit `spec`. Read §5.3 on `stamp` first.
 
+To watch a run bar by bar, add `record=True`: the report is byte-identical (recording is
+observation only, pinned by a golden), `Report.replay` carries every frame, and
+`report.to_html(path)` grows a second tab holding the replay cockpit — decisions with the
+broker's answers, rejections included, fills, indicator values named by their attributes,
+running stats on the tape and beside it, and the session enforcement between bars. `self.note("why")` inside a hook is the narrative channel:
+the recorder captures WHAT on its own; only the strategy can say WHY. It is a pure sink — a
+no-op unrecorded, and never able to influence the run. `report.replay_json(path)` dumps the
+raw recording.
+
 ## 3. Public API surface
 
 Generated from the live objects — every signature below is real.
@@ -93,8 +111,8 @@ Generated from the live objects — every signature below is real.
 
 | Name | Signature | What it does |
 |---|---|---|
-| `Backtest` | `(data: 'Sequence[Bar]', strategy: 'Strategy', account: 'AccountSize' = <AccountSize.S50K: '50K'>, dll_enabled: 'bool' = False, validate: 'bool' = True, account_id: 'int' = 1, fill_config: 'BarFillConfig \| None' = None, broker_config: 'SimBrokerConfig \| None' = None, fee_model: 'TopstepFees \| None' = None, **rejected: 'object')` | The two-line runner: assemble the sim stack correctly and run it once. |
-| `Report` | `(result: 'BacktestResult', stats: 'SummaryStats', trades: 'tuple[HalfTradeModel, ...]', params: 'CombineParams', bars_gated: 'int \| None' = None, bars: 'tuple[Bar, ...]' = (), instruments: 'dict[str, InstrumentSpec] \| None' = None)` | One run's full report: the untouched frozen ``BacktestResult``, derived |
+| `Backtest` | `(data: 'Sequence[Bar]', strategy: 'Strategy', account: 'AccountSize' = <AccountSize.S50K: '50K'>, dll_enabled: 'bool' = False, validate: 'bool' = True, record: 'bool' = False, account_id: 'int' = 1, fill_config: 'BarFillConfig \| None' = None, broker_config: 'SimBrokerConfig \| None' = None, fee_model: 'TopstepFees \| None' = None, **rejected: 'object')` | The two-line runner: assemble the sim stack correctly and run it once. |
+| `Report` | `(result: 'BacktestResult', stats: 'SummaryStats', trades: 'tuple[HalfTradeModel, ...]', params: 'CombineParams', bars_gated: 'int \| None' = None, bars: 'tuple[Bar, ...]' = (), instruments: 'dict[str, InstrumentSpec] \| None' = None, replay: 'Replay \| None' = None)` | One run's full report: the untouched frozen ``BacktestResult``, derived |
 | `AccountSize` | `AccountSize.S50K \| AccountSize.S100K \| AccountSize.S150K` | The three Trading Combine account sizes Topstep offers. |
 | `DataValidationError` | `(issues: 'tuple[ValidationIssue, ...]')` | Bar data failed validation; ``issues`` carries every ERROR finding. |
 
@@ -115,7 +133,7 @@ Generated from the live objects — every signature below is real.
 
 | Name | Signature | What it does |
 |---|---|---|
-| `NetPosition` | `(net: 'int' = 0)` | Signed net contracts for one instrument (positive = long). |
+| `NetPosition` | `(net: 'int' = 0, avg_price: 'Decimal \| None' = None)` | Signed net contracts for one instrument (positive = long), and the average price they were entered at. |
 | `PositionTracker` | `()` | Per-contract ``NetPosition``s, routed by ``contract_id``. |
 | `OrderTracker` | `()` | Latest ``OrderModel`` per order id, folded from ``on_order`` events. |
 
@@ -152,7 +170,16 @@ Generated from the live objects — every signature below is real.
 
 | Name | Signature | What it does |
 |---|---|---|
-| `render_html` | `(report: 'Report') -> 'str'` | Render ``report`` as one self-contained interactive HTML document. |
+| `render_html` | `(report: 'Report', *, replay: 'ReplaySpec' = 'auto') -> 'str'` | Render ``report`` as one self-contained interactive HTML document. |
+
+**Replay recording**
+
+| Name | Signature | What it does |
+|---|---|---|
+| `Replay` | `(*args, **kwargs)` | One recorded run: everything the tearsheet's replay scrubber shows. |
+| `StatsSnapshot` | `(*args, **kwargs)` | Running statistics as of a frame's settle — a full ``SummaryStats`` over the run's prefix, computed by the sa… |
+| `OrderIntent` | `(*args, **kwargs)` | One strategy decision at the ``ctx`` seam, with its outcome. |
+| `Recorder` | `()` | Engine-side run recorder. Observes; never influences. |
 
 **Tuning**
 
@@ -227,6 +254,9 @@ Generated from the live objects — every signature below is real.
 | `SymbolStrategy.sell` | `(self, size: 'int', *, stop_loss_ticks: 'int \| None' = None, take_profit_ticks: 'int \| None' = None, limit_price: 'Decimal \| None' = None, stop_price: 'Decimal \| None' = None, custom_tag: 'str \| None' = None) -> 'int \| None'` | Sell this contract (market unless a price kwarg implies otherwise); |
 | `SymbolStrategy.close` | `(self) -> 'None'` | Flatten this contract's position; a rejection goes to ``on_reject``. |
 | `SymbolStrategy.cancel_working` | `(self) -> 'None'` | Cancel every working order on this contract, one cancel per order; |
+| `SymbolStrategy.move_stop` | `(self, *, price: 'Decimal \| None' = None, ticks: 'int \| None' = None) -> 'int'` | Move every bracket stop on this contract; returns how many moved. |
+| `SymbolStrategy.move_target` | `(self, *, price: 'Decimal \| None' = None, ticks: 'int \| None' = None) -> 'int'` | Move every bracket take-profit on this contract; returns how many moved. |
+| `SymbolStrategy.note` | `(self, text: 'str') -> 'None'` | Attach a free-text breadcrumb to the current bar's replay frame. |
 | `SymbolStrategy.on_bar` | `(self, bar: 'Bar') -> 'None'` | — |
 | `SymbolStrategy.on_fill` | `(self, trade: 'HalfTradeModel') -> 'None'` | — |
 | `SymbolStrategy.on_reject` | `(self, error: 'APIError') -> 'None'` | Called with the ``APIError`` when a sugar order call is rejected. |
@@ -323,8 +353,10 @@ broker, clock or fill model. That is what makes the class run live unchanged.
 | `ctx.account_id` | first positional argument to every `orders`/`positions` call |
 | `ctx.instrument(cid)` | `InstrumentSpec` — tick size, tick value, session metadata |
 
-`SymbolStrategy` is sugar over exactly that: `buy/sell/close/cancel_working`, `self.position`
-(`flat`/`is_long`/`is_short`), `self.working_orders`, `self.spec`, `self.bars_gated`. **The sugar
+`SymbolStrategy` is sugar over exactly that: `buy/sell/close/cancel_working`, plus
+`move_stop/move_target` over the bracket children (`stop_orders`/`target_orders` are the
+filtered views), `self.position` (`flat`/`is_long`/`is_short`/`avg_price`),
+`self.working_orders`, `self.spec`, `self.bars_gated`. **The sugar
 does not raise** — it catches `APIError`, routes it to `on_reject` and returns `None`;
 `self.ctx.orders` is the raising path. Both are counted in the rejection tally (§5.5).
 
@@ -727,9 +759,10 @@ order placement — the SDK is async and the `await`s ARE the live contract. Tra
 | `self.data.Close[-1]` | the `bar` argument; `ctx.history.retrieve_bars(…)` for seen history |
 | `crossover(fast, slow)` | `self.use(Cross(fast, slow))` → `.up` / `.down` |
 | `self.buy(size=2, sl=…, tp=…)` | `await self.buy(2, stop_loss_ticks=40, take_profit_ticks=80)` |
+| `trade.sl = price` / `trade.tp = price` | `await self.move_stop(price=…)` / `move_target(price=…)` — or `ticks=` from `position.avg_price`, signed in the position's favour. These amend REAL working orders, so a rejection is real too |
 | `stats = bt.run()` → 30-key Series | `report = bt.run()` → `Report` + `.stats`/`.result`/`.trades` |
 | `optimize()` | `metrics.optimize(...)` — but read §5.9 first; it keeps every trial on purpose |
-| `plot()` | `report.show()` — interactive HTML tearsheet (`report.to_html(path)` to name the file; `bt.run_with_tearsheet(dir)` to get one from every run) |
+| `plot()` | `report.show()` — interactive HTML tearsheet (`report.to_html(path)` to name the file; `bt.run_with_tearsheet(dir)` to get one from every run; `Backtest(..., record=True)` adds the bar-by-bar replay tab) |
 
 ## 8. Knobs — the calibration seam
 
@@ -803,6 +836,7 @@ moving one toward optimism is a probe to report next to the baseline, not a new
 | `metrics/economics.py` | `evaluate_ev` + `EvalEconomics` — EV per attempt from YOUR prices; lead with `breakeven_pass_value` |
 | `data/continuous.py` | `stitch_continuous` — many expiries → one back-adjusted series on the bare ticker (§5.10) |
 | `indicators/` | TA-Lib adapter (152 of 161 functions), typed wrappers, `Cross`, `Indicator`/`ValueSource` |
+| `replay.py` | `Recorder` + `Replay` — bar-by-bar run recording behind `Backtest(record=True)`: decisions at the ctx seam (via recording proxies), events, indicator values, state tracks, sparse `SummaryStats` snapshots built by the SAME `metrics/stats` helpers (terminal snapshot pinned equal to `compute_summary`). Observation only: results are byte-identical either way |
 | `harness.py` | `Backtest` facade (one shared clock, instruments from the feed, strict validation, refuses backtesting.py knobs) and `Report` |
 
 ## 11. Not built — do not write code against it

{topstep_backtest-0.2.2 → topstep_backtest-0.3.0}/CHANGELOG.md

@@ -4,7 +4,120 @@ 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.
 
-## [Unreleased]
+## [0.3.0] — 2026-08-20
+
+A minor: new features, no intended breaking changes.
+
+### Added
+
+- **Bar-by-bar replay of a run.** `Backtest(..., record=True)` hooks a recorder into the
+  engine and `Report.replay` carries the full recording (`replay.py`): every decision at the
+  `ctx` seam with its exact parameters and the broker's answer — rejections keep their
+  gateway code and message instead of being flattened to a count — every order event, fill
+  (gross P&L + costs), position snapshot, session enforcement (16:10 flatten, session close,
+  MLL breach, DLL lockout), per-bar indicator values named by the attribute the strategy
+  stores them under (`self.fast = self.use(Sma(20))` records as `fast`; multi-output
+  indicators record line by line; `Cross` fires are events), warmup-gated bars as a state
+  rather than a hole, and change-only tracks of position / working orders / balance folded
+  from the same SDK events the strategy's own views fold. **Recording is observation only**:
+  results are byte-identical with it on or off, and `Strategy.note()` — the new narrative
+  breadcrumb channel (`self.note("why")` inside any hook, tagged with the hook that said it)
+  — is a pure sink that cannot influence a run. Both pinned by goldens
+  (`tests/golden/test_replay_goldens.py`).
+- **Running statistics that cannot drift from the report.** The recording carries sparse
+  `SummaryStats` snapshots (one per closing trade, day close, and breach — never per bar),
+  each computed over the run's *prefix* by the same `metrics.stats` code `compute_summary`
+  uses: the shared helpers were extracted for this (`compute_trade_close_stats`,
+  `compute_daily_stats`, `compute_round_trip_stats`, `compute_eod_drawdown`,
+  `sortino_ratio`, `exposure_fraction` — `compute_summary`'s behavior is unchanged), and the
+  only hand-rolled parts are the O(1) equity folds. The terminal snapshot is golden-pinned
+  byte-equal to `compute_summary` and property-swept across tapes
+  (`tests/property/test_replay_props.py`). One documented exception: `exposure` refreshes at
+  day closes only (the single prefix stat with no exact incremental form) and is exact again
+  at the terminal snapshot.
+- **The tearsheet grows a replay tab** when the report carries a recording. The page splits
+  into *results* (the finished run) and *replay · bar by bar*, a cockpit sized to the
+  viewport — charts down one side, the settled state and running stats beside them, the
+  event log alongside — so stepping a run never means scrolling between the tape and the
+  panel that explains it. Step it bar by bar (buttons, slider, ←/→ with shift for ×10,
+  Home/End, space to autoplay at 1, 5, 15 or 40 bars a second, click a chart or a log row
+  to jump); everything after the
+  cursor is veiled on every one of the replay tab's charts, so it shows only what the
+  strategy had seen, while the results tab keeps showing the run that finished. A strip
+  across the tape carries the live trade numbers at the cursor — position and average entry,
+  open P&L, the day, equity, floor headroom, and the closed-trade record so far (net P&L,
+  net win rate, trades) lifted from the running-stats snapshot in force, plus the cursor
+  bar's OHLC; the toolbar's `stats` button hides it. Charts follow the cursor in a
+  selectable window (whole run, or 60–480 bars — a long recording opens following, since
+  fitting 30,000 bars into a pane gives each one half a pixel), and their series' last-value
+  badges are off in favour of a price line at the cursor's own close and equity: a badge
+  reporting the end of a run the cursor has not reached is future information printed on the
+  axis of the one view that promises not to show any. The running stats mark every row the
+  newest snapshot moved (hover for the previous value) and say which snapshot of how many is
+  in force; the event log filters by kind, with counts, and says how many rows are hidden. Panels show the settled state at the cursor (position, working
+  orders — also drawn as price lines on the candlestick pane — balance, equity, floor
+  headroom, today's P&L), the indicator lines on their own synced chart with cross fires
+  marked on the tape, the running-stats snapshot in force, and a filterable-by-eye event log
+  with rejections loud. The open tab rides in the URL fragment (`#replay`), so a reload — or
+  a link to an archived file — comes back to the view it was left on. All figures are Python-preformatted by
+  the same helpers as the rest of the page; the JS computes nothing beyond differences of
+  two displayed numbers. Long tapes embed a **loudly labelled window** past
+  `REPLAY_AUTO_FRAME_LIMIT` (20,000) frames — breach-centred when there is a breach, else
+  the tail — and `to_html(path, replay=(start, end) | "full" | "off")` overrides it
+  (`show()`, `to_timestamped_html()` and `run_with_tearsheet()` forward the same knob).
+  Payload schema version bumps to 2.
+- **Amending a live bracket, and the average entry price to measure it from.**
+  `SymbolStrategy.move_stop(...)` / `move_target(...)` amend the reduce-only stop and limit
+  the venue creates when an entry fills, taking either `price=` (absolute, passed to the
+  broker as given) or `ticks=` — an offset from the average entry signed **in the position's
+  favour**, so `ticks=0` is breakeven and `ticks=10` is ten ticks of locked profit long or
+  short. They act on bracket children only (`parent_order_id` set), so a stop-*entry* of
+  your own is never mistaken for protection; they move every child (a scale-in has several)
+  and return the count; rejections go to `on_reject` as with every other sugar call. A level
+  measured off the average is snapped to the tick grid **against** the position, because the
+  venue's average is quantized to tick/100 and a stop rounding toward profit would lock in a
+  tick the entry cannot support. `stop_orders` / `target_orders` expose the same filtered
+  view. Amended levels are live from the next bar, which the `accepted_ts` firewall
+  guarantees and an end-to-end test pins by exit price.
+- **`position.avg_price`** — the venue's display average (`PositionModel.average_price`),
+  which the position view previously discarded. Carried from snapshots rather than
+  re-derived, so no second averaging convention is invented for a number the gateway
+  publishes; fills keep it honest where they can do so exactly (opening from flat, flipping
+  through it, flattening), and a scale-in leaves the previous average standing until the
+  snapshot corrects it — the next event in the sim, one hub round trip live.
+- `Report.replay_json(path)` dumps the raw recording as JSON — for diffing two runs or
+  verifying what was captured without a browser in the way. `SymbolStrategy` gains a
+  read-only `registered_indicators`; `SimBroker` gains O(1) `last_bar_equity`.
+  `examples/run_replay.py` shows the whole flow, narrated.
+
+## [0.2.3] — 2026-08-16
+
+### Fixed
+
+- The `[data]` and `[dev]` extras now install `pyarrow`, so **Parquet input works out of the
+  box**. `examples/run_real_data.py` has always branched to `pd.read_parquet` on a `.parquet` /
+  `.pq` suffix, but pandas ships no Parquet engine of its own — so `[data]` alone met that
+  branch with `ImportError: Unable to find a usable engine`, on the format most vendors
+  (Databento included) actually export. Deliberately unbounded, unlike `topstep-sdk` and
+  `ta-lib`: a breaking `pyarrow` major fails loudly at read time instead of quietly changing a
+  number. Reading the same bars from CSV and from Parquet produces a byte-identical report.
+
+  Released as 0.2.3, not 0.2.2: the `v0.2.2` tag was cut from a commit three minutes before
+  this change merged, so **0.2.2 shipped without pyarrow** and its Parquet path fails exactly
+  as 0.2.1's did. A PyPI version can never be re-uploaded, so the fix moved forward a version
+  rather than the tag moving backward.
+
+## [0.2.2] — 2026-08-16
+
+### Fixed
+
+- Repository plumbing only; no user-facing change. `ruff format` also formats Python inside
+  markdown fences, so the tearsheet examples added to the README and `website/results.md` in
+  0.2.1 were unformatted code and CI had been red since — through two merges. And the docs
+  workflow's `actions/configure-pages` step called the Pages REST API under a `contents: read`
+  token, failing every deploy with "Resource not accessible by integration" while blaming the
+  repository's Pages settings; MkDocs takes its base URL from `site_url`, so the step was
+  removed rather than the token widened.
 
 ## [0.2.1] — 2026-08-16
 
@@ -309,4 +422,5 @@ rule and fee constants are **not yet calibrated against a live account**, so a
   are not exercised end to end.
 - Tier-0 bar fills only. No quote, depth or MBO tiers.
 
+[0.3.0]: https://pypi.org/project/topstep-backtest/0.3.0/
 [0.1.0]: https://pypi.org/project/topstep-backtest/0.1.0/

{topstep_backtest-0.2.2 → topstep_backtest-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: topstep-backtest
-Version: 0.2.2
+Version: 0.3.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
@@ -23,9 +23,11 @@ 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'
+Requires-Dist: pyarrow>=17; extra == 'data'
 Provides-Extra: dev
 Requires-Dist: hypothesis>=6.100; extra == 'dev'
 Requires-Dist: pandas>=2.2; extra == 'dev'
+Requires-Dist: pyarrow>=17; 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'
@@ -69,6 +71,12 @@ class SmaCross(SymbolStrategy):
             await self.buy(2, stop_loss_ticks=40, take_profit_ticks=80)  # signed-tick OCO
 ```
 
+The bracket becomes two real reduce-only orders when the entry fills, so a running trade can
+be managed rather than only abandoned: `await self.move_stop(ticks=0)` pulls every bracket
+stop to breakeven (`ticks` is signed in the position's favour and measured from
+`self.position.avg_price`, the venue's own average), `move_target` does the same for the
+take-profit, and both return how many orders moved.
+
 **Every named indicator is a typed alias for a TA-Lib function**, not a
 reimplementation: `Sma(20)` *is* `TalibIndicator("SMA", timeperiod=20)`, and the generic
 form reaches 152 of TA-Lib's 161 functions directly. Nothing in this repo implements an
@@ -80,7 +88,7 @@ framework helper that compares two TA-Lib outputs rather than computing anything
 
 ```bash
 pip install topstep-backtest
-pip install "topstep-backtest[data]"   # adds pandas, for DataFrame input
+pip install "topstep-backtest[data]"   # adds pandas + pyarrow: DataFrame and Parquet input
 ```
 
 Requires Python 3.12+. TA-Lib is a core dependency and ships wheels for common platforms;
@@ -175,6 +183,26 @@ cannot disagree. For a sheet from *every* run without naming a file each time,
 `Backtest(...).run_with_tearsheet("runs")` writes `tearsheet-<UTC stamp>.html` and returns
 both the report and the path.
 
+**Replay a run bar by bar.** Pass `record=True` and the tearsheet grows a second tab: a
+replay cockpit that fills the window — its own charts on one side, the settled state, the
+running stats and the event log on the other, so nothing has to be scrolled between. Step
+through the run (buttons, slider, arrow keys, autoplay) with everything after the cursor
+veiled, and watch the position, working orders (drawn as price lines), balance, floor
+headroom, indicator values — named by the attributes your strategy stores them under — and
+the running statistics as they accumulated, computed by the same code as the final report so
+they cannot disagree with it. A strip across the tape carries the live trade numbers at the
+cursor: the bar's OHLC, position and average entry, open P&L, the day, floor headroom, and
+the closed-trade record so far. The charts follow the cursor in a window you pick (or fit the
+whole run), the price axis labels the cursor's own close rather than the run's last — nothing
+on a replay chart reports a bar the strategy had not reached — the stats mark what the newest
+snapshot moved, and the event log filters by kind. The event log lists every decision with the exact parameters
+and the broker's answer (rejections stay loud), every fill with its P&L and costs, and the
+session enforcement between bars; `self.note("why")` inside a hook adds your own narrative at
+the decision point. Recording is observation only — the report is byte-identical with it on
+or off, pinned by a golden test — and `report.replay_json(path)` dumps the raw recording.
+Long tapes embed a loudly-labelled window (`replay=(start, end)` chooses it;
+`replay="full"` forces everything).
+
 Then stop trusting one sample:
 
 ```python
@@ -300,9 +328,10 @@ environment. There is no public issue tracker.
   (XFA) modeling is deliberately parked.
 - `examples/` — runnable: `run_real_data.py` (your CSV/Parquet → verdict), `run_combine.py`
   (synthetic end to end), `run_tearsheet.py` (the same run as one HTML file),
-  `run_montecarlo.py` (outcome distribution + autopsy), `run_windows.py` (a long tape
-  replayed as consecutive independent Combine attempts), `ema_cross.py`, `sma_cross.py`,
-  `talib_macd.py`, `hand_wired.py` (what the facade assembles).
+  `run_replay.py` (a recorded run with the bar-by-bar scrubber), `run_montecarlo.py`
+  (outcome distribution + autopsy), `run_windows.py` (a long tape replayed as consecutive
+  independent Combine attempts), `ema_cross.py`, `sma_cross.py`, `talib_macd.py`,
+  `hand_wired.py` (what the facade assembles).
 
 ## Stack
 

{topstep_backtest-0.2.2 → topstep_backtest-0.3.0}/README.md

@@ -29,6 +29,12 @@ class SmaCross(SymbolStrategy):
             await self.buy(2, stop_loss_ticks=40, take_profit_ticks=80)  # signed-tick OCO
 ```
 
+The bracket becomes two real reduce-only orders when the entry fills, so a running trade can
+be managed rather than only abandoned: `await self.move_stop(ticks=0)` pulls every bracket
+stop to breakeven (`ticks` is signed in the position's favour and measured from
+`self.position.avg_price`, the venue's own average), `move_target` does the same for the
+take-profit, and both return how many orders moved.
+
 **Every named indicator is a typed alias for a TA-Lib function**, not a
 reimplementation: `Sma(20)` *is* `TalibIndicator("SMA", timeperiod=20)`, and the generic
 form reaches 152 of TA-Lib's 161 functions directly. Nothing in this repo implements an
@@ -40,7 +46,7 @@ framework helper that compares two TA-Lib outputs rather than computing anything
 
 ```bash
 pip install topstep-backtest
-pip install "topstep-backtest[data]"   # adds pandas, for DataFrame input
+pip install "topstep-backtest[data]"   # adds pandas + pyarrow: DataFrame and Parquet input
 ```
 
 Requires Python 3.12+. TA-Lib is a core dependency and ships wheels for common platforms;
@@ -135,6 +141,26 @@ cannot disagree. For a sheet from *every* run without naming a file each time,
 `Backtest(...).run_with_tearsheet("runs")` writes `tearsheet-<UTC stamp>.html` and returns
 both the report and the path.
 
+**Replay a run bar by bar.** Pass `record=True` and the tearsheet grows a second tab: a
+replay cockpit that fills the window — its own charts on one side, the settled state, the
+running stats and the event log on the other, so nothing has to be scrolled between. Step
+through the run (buttons, slider, arrow keys, autoplay) with everything after the cursor
+veiled, and watch the position, working orders (drawn as price lines), balance, floor
+headroom, indicator values — named by the attributes your strategy stores them under — and
+the running statistics as they accumulated, computed by the same code as the final report so
+they cannot disagree with it. A strip across the tape carries the live trade numbers at the
+cursor: the bar's OHLC, position and average entry, open P&L, the day, floor headroom, and
+the closed-trade record so far. The charts follow the cursor in a window you pick (or fit the
+whole run), the price axis labels the cursor's own close rather than the run's last — nothing
+on a replay chart reports a bar the strategy had not reached — the stats mark what the newest
+snapshot moved, and the event log filters by kind. The event log lists every decision with the exact parameters
+and the broker's answer (rejections stay loud), every fill with its P&L and costs, and the
+session enforcement between bars; `self.note("why")` inside a hook adds your own narrative at
+the decision point. Recording is observation only — the report is byte-identical with it on
+or off, pinned by a golden test — and `report.replay_json(path)` dumps the raw recording.
+Long tapes embed a loudly-labelled window (`replay=(start, end)` chooses it;
+`replay="full"` forces everything).
+
 Then stop trusting one sample:
 
 ```python
@@ -260,9 +286,10 @@ environment. There is no public issue tracker.
   (XFA) modeling is deliberately parked.
 - `examples/` — runnable: `run_real_data.py` (your CSV/Parquet → verdict), `run_combine.py`
   (synthetic end to end), `run_tearsheet.py` (the same run as one HTML file),
-  `run_montecarlo.py` (outcome distribution + autopsy), `run_windows.py` (a long tape
-  replayed as consecutive independent Combine attempts), `ema_cross.py`, `sma_cross.py`,
-  `talib_macd.py`, `hand_wired.py` (what the facade assembles).
+  `run_replay.py` (a recorded run with the bar-by-bar scrubber), `run_montecarlo.py`
+  (outcome distribution + autopsy), `run_windows.py` (a long tape replayed as consecutive
+  independent Combine attempts), `ema_cross.py`, `sma_cross.py`, `talib_macd.py`,
+  `hand_wired.py` (what the facade assembles).
 
 ## Stack
 

{topstep_backtest-0.2.2 → topstep_backtest-0.3.0}/docs/DESIGN.md

@@ -143,6 +143,47 @@ and a breakeven. `optimize()` was withheld until those guards existed — the or
 point, and reversing it (shipping a sweep whose output nothing deflates) would re-open this
 failure mode.
 
+### 3.9 The replay recorder observes at the engine's seams — never inside them (2026-08-17)
+
+`Backtest(record=True)` answers "what did the strategy see and decide on THIS bar", and the
+design constraint that shaped it is that **the answer must be worthless-proof: recording can
+never change the run.** Three placements follow:
+
+- **Capture at existing seams, add none.** The engine already has the phase boundaries
+  (`commit_bar` after a bar fully settles, `on_session` around enforcement, `on_user_event`
+  in the dispatch loop); decisions are captured by wrapping the strategy's `ctx.orders`/
+  `ctx.positions` in structurally-conformant recording proxies, so raw and sugar order paths
+  are seen identically and the broker is untouched. State tracks (position, working orders)
+  fold the SAME SDK events the strategy's own views fold (`strategy/tracker.py`) — never
+  broker internals, so the recording shows what a live session would have shown.
+- **Running statistics may not become a second implementation.** Snapshots call the same
+  `metrics/stats.py` helpers `compute_summary` calls (extracted for exactly this), over
+  prefix data; the only hand-rolled parts are the O(1) equity folds (peak/max-DD/static/
+  intraday trio), and the terminal snapshot is pinned byte-equal to `compute_summary` by
+  `tests/golden/test_replay_goldens.py` and swept across tapes by
+  `tests/property/test_replay_props.py`. Trade figures inside snapshots re-read
+  `broker.trades` (the ledger), not the recorder's event fold — events lag the ledger inside
+  a session roll, and a snapshot mixing the two would be internally inconsistent.
+- **The narrative channel is a pure sink.** `Strategy.note()` writes into the recording and
+  nowhere else; unrecorded it is a no-op. Byte-identity of results with recording on/off and
+  with/without notes is pinned by goldens — if either pin ever breaks, every recording made
+  since is suspect, which is why they are goldens and not unit tests.
+
+The tearsheet embeds the recording behind the same determinism contract as the rest of the
+render (Python-preformatted strings; JS computes nothing beyond differences of two displayed
+numbers), windowed with a loud label past `REPLAY_AUTO_FRAME_LIMIT` frames because a scrubber
+silently missing five sixths of a run reads as the whole run.
+
+The replay lives in its **own tab with its own charts**, not inline under the results sheet.
+Two reasons, and the second is the load-bearing one: a cockpit worth stepping through wants
+the chart, the state and the event log in one viewport rather than stacked down a scrolling
+column; and a veil belongs only on a run mid-flight. Sharing one set of charts meant the
+finished sheet was dimmed by wherever the cursor happened to sit — the results view is the
+run that *finished*, and it should say so. The cost is a second chart set built from the same
+payload (lazily, on first open: a chart created in a `display:none` container measures zero
+and opens on an empty time scale) and the drawing helpers shared, so two views of the same
+bars cannot drift apart.
+
 ---
 
 ## 4. Why the strategy dialect is shaped this way (2026-07-22)
@@ -219,7 +260,8 @@ Violations are bugs, not style. Most are pinned by a named test.
   `ruff format --check` is the one people forget — which is also why `ruff` is pinned
   `>=0.16,<0.17`: format output changes between minors, so an unbounded pin would fail CI on
   correctly formatted code. Runtime deps are `topstep-sdk`, `msgspec`, `ta-lib` (the last is
-  core, not an extra); exactly two extras exist, `[data]` and `[dev]`.
+  core, not an extra); exactly three extras exist, `[data]` (pandas + pyarrow, so both
+  DataFrame and Parquet input work), `[dev]` and `[docs]`.
 
 ## 6. Testing idioms
 

{topstep_backtest-0.2.2 → topstep_backtest-0.3.0}/docs/ROADMAP.md

@@ -11,7 +11,7 @@ in [`topstep-rules.md`](./topstep-rules.md).
 | 3. SimBroker + Tier-0 fills + rules wired | `fills/bar_fill.py::BarFillModel`, `fills/fees.py::TopstepFees`, netting/PnL, intrabar mark path, forced liquidation | **Done** — the mark/breach walk and forced liquidation are inside `SimBroker`, not separate components |
 | 4. Strategy API + parity gate | `Strategy`/`StrategyContext`, `SymbolStrategy`, reference MA-cross strategies | **Partial** — API and `examples/{sma,ema}_cross.py` ship; the intent-sequence gate is **NOT met**. Only *structural* parity is proven (pyright-strict protocol conformance + a `place()` keyword diff, `tests/parity/test_broker_conformance.py`) |
 | 5. Data layer | Parquet/Arrow catalog, validator, warmup, causal continuous-contract stitcher | **Partial** — `data/validator.py`, `SymbolStrategy` warmup and `data/continuous.py::stitch_continuous` ship (additive back-adjustment, volume or explicit rolls, tick-exact offsets, `RollEvent` metadata). No Parquet/Arrow catalog |
-| 6. Analytics | Decimal-path metrics + tearsheet; Monte-Carlo pass-probability; overfitting guards (PBO/DSR/walk-forward) | **Partial** — `metrics/stats.py::compute_summary` covers trade stats (expectancy/payoff/streaks/breakeven cost), flat-to-flat round trips with true R-multiples plus dollar extremes and holding times, drawdown under all three prop conventions plus duration/recovery/mean-episode-depth/min-floor-headroom, the daily-P&L distribution with a dollar standard deviation, exposure, the equity peak, the run window, and Sortino/Calmar. `metrics/montecarlo.py::monte_carlo` block-bootstraps observed days through the real `CombineKernel` for pass probability, a violation autopsy (MLL breach / consistency-blocked / target-not-reached) and days-to-target. `metrics/overfitting.py::deflated_sharpe` + `TrialLedger` deflate a Sharpe by the recorded trial count, and `metrics/economics.py::evaluate_ev` turns a pass probability plus YOUR prices into an EV and a breakeven. `metrics/walkforward.py` adds `optimize` (which keeps every trial, not just the winner), anchored `walk_forward` with efficiency, and `metrics/overfitting.py::probability_of_backtest_overfitting` (CSCV). `optimize()` was deferred for a long time as an overfitting machine; it ships now *because* DSR and PBO exist to catch what it produces. The interactive HTML tearsheet ships: `report.to_html(path)` / `report.show()` render one self-contained file (candlestick tape with fills marked, equity vs the trailing MLL floor, daily P&L, R-multiple distribution, and every text-render stat with its basis label; `tearsheet/`, charting via vendored Lightweight Charts). **One deliverable remains: per-year / per-regime breakdowns. Not blocked — the Phase-5 stitcher they waited on now ships** |
+| 6. Analytics | Decimal-path metrics + tearsheet; Monte-Carlo pass-probability; overfitting guards (PBO/DSR/walk-forward) | **Partial** — `metrics/stats.py::compute_summary` covers trade stats (expectancy/payoff/streaks/breakeven cost), flat-to-flat round trips with true R-multiples plus dollar extremes and holding times, drawdown under all three prop conventions plus duration/recovery/mean-episode-depth/min-floor-headroom, the daily-P&L distribution with a dollar standard deviation, exposure, the equity peak, the run window, and Sortino/Calmar. `metrics/montecarlo.py::monte_carlo` block-bootstraps observed days through the real `CombineKernel` for pass probability, a violation autopsy (MLL breach / consistency-blocked / target-not-reached) and days-to-target. `metrics/overfitting.py::deflated_sharpe` + `TrialLedger` deflate a Sharpe by the recorded trial count, and `metrics/economics.py::evaluate_ev` turns a pass probability plus YOUR prices into an EV and a breakeven. `metrics/walkforward.py` adds `optimize` (which keeps every trial, not just the winner), anchored `walk_forward` with efficiency, and `metrics/overfitting.py::probability_of_backtest_overfitting` (CSCV). `optimize()` was deferred for a long time as an overfitting machine; it ships now *because* DSR and PBO exist to catch what it produces. The interactive HTML tearsheet ships: `report.to_html(path)` / `report.show()` render one self-contained file (candlestick tape with fills marked, equity vs the trailing MLL floor, daily P&L, R-multiple distribution, and every text-render stat with its basis label; `tearsheet/`, charting via vendored Lightweight Charts). Bar-by-bar replay ships: `Backtest(record=True)` records every decision/event/indicator value/running-stats snapshot (`replay.py`, observation-only, golden-pinned byte-identical results) and the tearsheet grows a scrubber over it. **One deliverable remains: per-year / per-regime breakdowns. Not blocked — the Phase-5 stitcher they waited on now ships** |
 | 7. Live adapter + calibration | `LiveBroker` shim over `topstep-sdk`, captured-gateway fixtures, field-level parity diff, calibration vs a real eval account | **Not started** — nothing has run against a real account; fee and rule constants are uncalibrated |
 | 8. Higher fill tiers | `QuoteFillModel` → `DepthFillModel` → `MBOFillModel` (CME FIFO) | **Not started** — Tier-0 only |
 | — Parked: Express Funded (XFA) | Funded phase (scaling, payout paths, post-first-payout MLL→0) as a new `RuleSet` | **Parked** — only after the Combine path is trustworthy |

{topstep_backtest-0.2.2 → topstep_backtest-0.3.0}/docs/TUTORIAL_EMA_CROSSOVER.md

@@ -300,6 +300,29 @@ contract. Like `buy`, a rejection routes to `on_reject`; it fills at the **next*
 bar's open (§7). `cancel_working()` is the companion that cancels every working
 order on the contract.
 
+### Beyond the listing: managing the trade you are already in
+
+`EmaCross` enters and then waits — the bracket or a cross-down ends the trade.
+It does not have to be that way. The bracket from step (5) became two real
+reduce-only orders the moment the entry filled, so a strategy can amend it
+without closing anything:
+
+```python
+entry = self.position.avg_price  # the venue's average; None when flat
+if self.position.is_long and entry is not None:
+    if bar.close - entry >= 20 * self.spec.tick_size:
+        await self.move_stop(ticks=0)  # stop to breakeven
+```
+
+`ticks=` is measured from the average entry and signed **in the position's
+favour**, so `ticks=0` is breakeven and `ticks=10` is ten ticks of locked
+profit whether the trade is long or short; `price=` sets an absolute level
+instead. Both return how many orders moved — every bracket child, since a
+scale-in has more than one — and route rejections to `on_reject`. They touch
+bracket children only, so an entry order of your own resting in the market is
+never mistaken for protection. The new level is live from the **next** bar, for
+the same reason a market order fills at the next bar's open.
+
 ### Swapping the EMAs for any other TA-Lib indicator
 
 Because `Ema` is only a typed spelling of a TA-Lib call, changing the *signal*

topstep_backtest-0.3.0/examples/run_replay.py

@@ -0,0 +1,101 @@
+"""Record a run bar by bar and step through it in the tearsheet's replay.
+
+Same assembly as ``examples/run_tearsheet.py`` with ONE knob added:
+``Backtest(..., record=True)``. Recording is observation only — the report is
+byte-identical to an unrecorded run — but ``Report.replay`` then carries every
+frame, and the HTML tearsheet grows a second tab, ``replay · bar by bar``: a
+cockpit sized to the window, charts on one side and panels on the other, so
+nothing has to be scrolled between:
+
+* step the run bar by bar (buttons, slider, arrow keys; space to autoplay) —
+  everything after the cursor is veiled, so the page shows only what the
+  strategy had seen (the results tab keeps showing the finished run);
+* a strip across the tape carries the live trade numbers at the cursor: the
+  position and its average entry, open P&L, the day, equity, floor headroom,
+  and the closed-trade record so far;
+* the state panel shows the position, working orders (drawn as price lines on
+  the candlestick pane), balance, equity, floor headroom and today's P&L as
+  of the cursor;
+* the running-stats panel replays ``SummaryStats`` as it accumulated —
+  snapshots land on every closing trade and day close, computed by the same
+  code that produces the final report, so the numbers cannot disagree;
+* the event log lists every decision the strategy made (with the exact order
+  parameters and the broker's answer, rejections included), every fill with
+  its P&L and costs, every ``self.note(...)`` breadcrumb, and every session
+  enforcement (16:10 flatten, session close, MLL/DLL) — click a row to jump.
+
+``self.note(...)`` is the narrative channel: the recorder can capture WHAT
+happened on its own, but only the strategy knows WHY, so say it at the
+decision point and read it back at the same bar in the log.
+
+Long runs: ``report.to_html(path)`` embeds every frame up to a documented
+limit and then falls back to a loudly-labelled window (centred on the MLL
+breach when there is one). ``to_html(path, replay=(start, end))`` picks the
+window by hand; ``replay="full"`` forces everything; ``replay="off"`` renders
+the classic sheet. ``report.replay_json(path)`` dumps the raw recording for
+anything a browser page is the wrong tool for.
+
+    uv run python examples/run_replay.py
+"""
+
+from __future__ import annotations
+
+from datetime import date
+from decimal import Decimal
+from pathlib import Path
+
+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
+from topstep_backtest.protocols import Bar
+
+CONTRACT = "CON.F.US.MNQ.U26"
+
+
+class NarratedSmaCross(SymbolStrategy):
+    """The quickstart SMA cross, narrating its decisions for the replay."""
+
+    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: Bar) -> None:
+        if self.cross.up and self.position.flat:
+            self.note(f"fast {self.fast.value} crossed above slow {self.slow.value}: long 2")
+            await self.buy(2, stop_loss_ticks=40, take_profit_ticks=80)
+        elif self.cross.down and self.position.is_long:
+            self.note("down-cross with a long on: closing")
+            await self.close()
+
+
+def main() -> None:
+    bars = synthetic_bars(
+        contract_id=CONTRACT,
+        spec=spec_for_symbol("MNQ"),
+        start_day=date(2026, 5, 4),
+        days=10,
+        seed=7,
+        start_price=Decimal("23000.00"),
+        bars_per_day=120,
+        vol_ticks=12,
+    )
+    report = Backtest(bars, NarratedSmaCross(CONTRACT), account=AccountSize.S50K, record=True).run()
+    print(report)
+
+    replay = report.replay
+    assert replay is not None  # record=True was passed
+    print(
+        f"\nrecorded {replay.frame_count} frames: "
+        f"{len(replay.intents)} decisions, {len(replay.fill_events)} fills, "
+        f"{len(replay.notes)} notes, {len(replay.snapshots)} stat snapshots"
+    )
+
+    written = report.to_html(Path("replay-tearsheet.html"))
+    print(f"wrote {written.resolve()} — open it, take the replay tab, press space")
+
+
+if __name__ == "__main__":
+    main()

{topstep_backtest-0.2.2 → topstep_backtest-0.3.0}/pyproject.toml

@@ -37,13 +37,24 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
-data = ["pandas>=2.2"]
+data = [
+    "pandas>=2.2",
+    # pandas reads Parquet only through a third-party engine and ships none, so
+    # `[data]` without this turns every .parquet export — the format Databento
+    # and most vendors hand you — into an ImportError at load time. No upper
+    # bound, unlike topstep-sdk and ta-lib above: a breaking pyarrow major fails
+    # LOUDLY at read time rather than quietly changing a number, so pinning it
+    # out would buy nothing and strand the extra on an old wheel.
+    "pyarrow>=17",
+]
 dev = [
     "pytest>=8.0",
     "pytest-asyncio>=0.24",
     "pytest-cov>=5.0",
     "hypothesis>=6.100",
     "pandas>=2.2",
+    # Mirrors `[data]`: the Parquet path needs an engine to be exercised at all.
+    "pyarrow>=17",
     # ruff is PINNED to a minor range on purpose: `ruff format --check` runs in
     # CI, and formatting output changes between ruff minors. Unbounded, CI would
     # spontaneously fail on code that is correctly formatted locally. Bump this