topstep-backtest 0.2.3__tar.gz → 0.4.0__tar.gz

{topstep_backtest-0.2.3 → topstep_backtest-0.4.0}/.gitignore

@@ -42,5 +42,8 @@ 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
+mc-confidence-tearsheet.html
+spaced-tearsheet.html

{topstep_backtest-0.2.3 → topstep_backtest-0.4.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. |
 
@@ -109,13 +127,13 @@ Generated from the live objects — every signature below is real.
 
 | Name | Signature | What it does |
 |---|---|---|
-| `SymbolStrategy` | `(contract_id: 'str', require_ready: 'bool' = True, warmup: 'int \| None' = None)` | Base for strategies trading exactly one contract. |
+| `SymbolStrategy` | `(contract_id: 'str', require_ready: 'bool' = True, warmup: 'int \| None' = None, trade_sessions: 'Sequence[Session] \| None' = None)` | Base for strategies trading exactly one contract. |
 
 **Position / order views**
 
 | 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. |
 
@@ -126,11 +144,17 @@ Generated from the live objects — every signature below is real.
 | `bars_from_dataframe` | `(df: 'Any', *, contract_id: 'str', spec: 'InstrumentSpec', unit: 'AggregateBarUnit', unit_number: 'int', stamp: "Literal['open', 'close']") -> 'tuple[Bar, ...]'` | Build ``Bar`` objects from a pandas DataFrame of OHLCV candles. |
 | `bars_from_records` | `(rows: 'Iterable[tuple[object, ...]]', *, contract_id: 'str', spec: 'InstrumentSpec', unit: 'AggregateBarUnit', unit_number: 'int', stamp: "Literal['open', 'close']") -> 'tuple[Bar, ...]'` | Build tick-grid-validated ``Bar`` objects from ``(ts, o, h, l, c, v)`` rows. |
 
+**Data in (Parquet export)**
+
+| Name | Signature | What it does |
+|---|---|---|
+| `load_bars` | `(path: 'str \| Path') -> 'tuple[tuple[Bar, ...], InstrumentSpec, dict[str, Any]]'` | Read the export -> (bars, spec, metadata), ready for ``Backtest(...)``. |
+
 **Data in (synthetic)**
 
 | Name | Signature | What it does |
 |---|---|---|
-| `synthetic_bars` | `(*, contract_id: 'str', spec: 'InstrumentSpec', start_day: 'date', days: 'int', seed: 'int', start_price: 'Decimal', bars_per_day: 'int' = 390, unit: 'AggregateBarUnit' = <AggregateBarUnit.MINUTE: 2>, unit_number: 'int' = 1, drift_ticks_per_day: 'int' = 0, vol_ticks: 'int' = 8) -> 'tuple[Bar, ...]'` | Generate ``days`` trading sessions of consistent, on-grid OHLCV bars. |
+| `synthetic_bars` | `(*, contract_id: 'str', spec: 'InstrumentSpec', start_day: 'date', days: 'int', seed: 'int', start_price: 'Decimal', bars_per_day: 'int \| None' = None, unit: 'AggregateBarUnit' = <AggregateBarUnit.MINUTE: 2>, unit_number: 'int' = 1, drift_ticks_per_day: 'int' = 0, vol_ticks: 'int' = 8, hours: 'Hours' = 'rth') -> 'tuple[Bar, ...]'` | Generate ``days`` trading sessions of consistent, on-grid OHLCV bars. |
 
 **Instruments**
 
@@ -140,6 +164,15 @@ Generated from the live objects — every signature below is real.
 | `symbol_of_contract_id` | `(contract_id: 'str') -> 'str'` | Extract the product symbol from a gateway contract id. |
 | `InstrumentSpec` | `(*args, **kwargs)` | Frozen per-product economics and session metadata. |
 
+**Sessions**
+
+| Name | Signature | What it does |
+|---|---|---|
+| `Session` | `(*args, **kwargs)` | A named intraday window, defined in its own local timezone. |
+| `ASIA` | `Session(name='ASIA', tz='Asia/Tokyo', start=09:00:00, end=15:00:00)` | A named intraday window, defined in its own local timezone. |
+| `LONDON` | `Session(name='LONDON', tz='Europe/London', start=08:00:00, end=16:30:00)` | A named intraday window, defined in its own local timezone. |
+| `NEW_YORK` | `Session(name='NEW_YORK', tz='America/New_York', start=09:30:00, end=16:00:00)` | A named intraday window, defined in its own local timezone. |
+
 **Results**
 
 | Name | Signature | What it does |
@@ -152,7 +185,17 @@ 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', confidence: 'MonteCarloConfidence \| None' = None, crosscheck: 'CrossCheck \| None' = None) -> 'str'` | Render ``report`` as one self-contained interactive HTML document. |
+| `render_sweep_html` | `(sweep: 'WindowSweep \| SpacedSweep') -> 'str'` | Render a sweep as one self-contained 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**
 
@@ -172,12 +215,29 @@ Generated from the live objects — every signature below is real.
 | `MonteCarloResult` | `(*args, **kwargs)` | Outcome distribution over ``paths`` synthetic Combine attempts. |
 | `FailureMode` | `FailureMode.MLL_BREACH \| FailureMode.CONSISTENCY_BLOCKED \| FailureMode.TARGET_NOT_REACHED` | Why a simulated path did not pass. Ordered by when it is decided. |
 
+**Monte-Carlo confidence**
+
+| Name | Signature | What it does |
+|---|---|---|
+| `mc_confidence` | `(result: 'BacktestResult', *, params: 'CombineParams', paths: 'int' = 2000, horizon_days: 'int \| None' = None, block_length: 'int' = 5, seed: 'int' = 0, outer: 'int' = 200, inner_paths: 'int' = 200, lengths: 'Sequence[int]' = (1, 5, 10, 20)) -> 'MonteCarloConfidence'` | One call: the estimate plus its CI, sensitivity row, and year strata. |
+| `MonteCarloConfidence` | `(*args, **kwargs)` | The point estimate and every qualifier this module can attach to it. |
+| `pass_probability_ci` | `(result: 'BacktestResult', *, params: 'CombineParams', paths: 'int' = 2000, horizon_days: 'int \| None' = None, block_length: 'int' = 5, seed: 'int' = 0, outer: 'int' = 200, inner_paths: 'int' = 200) -> 'PassProbabilityCI'` | Double bootstrap: a confidence band for the pass probability. |
+| `PassProbabilityCI` | `(*args, **kwargs)` | A pass probability with the error bar its sample size actually earns. |
+| `block_length_sensitivity` | `(result: 'BacktestResult', *, params: 'CombineParams', lengths: 'Sequence[int]' = (1, 5, 10, 20), paths: 'int' = 1000, horizon_days: 'int \| None' = None, seed: 'int' = 0) -> 'BlockLengthSensitivity'` | Re-run the Monte Carlo across block lengths and report the swing. |
+| `BlockLengthSensitivity` | `(*args, **kwargs)` | The same estimate at several block lengths, plus how far it moved. |
+| `monte_carlo_by_year` | `(result: 'BacktestResult', *, params: 'CombineParams', paths: 'int' = 1000, horizon_days: 'int \| None' = None, block_length: 'int' = 5, seed: 'int' = 0) -> 'YearStratification'` | One Monte Carlo per calendar year of the source run. |
+| `YearStratification` | `(*args, **kwargs)` | Per-year estimates, ascending by year. |
+| `crosscheck` | `(mc: 'MonteCarloResult', sweep: 'WindowSweep') -> 'CrossCheck'` | Compare a Monte Carlo against a window sweep, outcome by outcome. |
+| `CrossCheck` | `(*args, **kwargs)` | The bootstrap and the window sweep, forced to answer side by side. |
+
 **Sequential Combines**
 
 | Name | Signature | What it does |
 |---|---|---|
 | `sequential_combines` | `(bars: 'Sequence[Bar]', factory: 'Callable[[], Strategy]', *, window_days: 'int', account: 'AccountSize' = <AccountSize.S50K: '50K'>, dll_enabled: 'bool' = False, warm_start: 'bool' = True, validate: 'bool' = True) -> 'WindowSweep'` | Run one fresh Combine per non-overlapping ``window_days``-day window. |
+| `spaced_combines` | `(bars: 'Sequence[Bar]', factory: 'Callable[[], Strategy]', *, window_days: 'int', periods: 'int', account: 'AccountSize' = <AccountSize.S50K: '50K'>, dll_enabled: 'bool' = False, warm_start: 'bool' = True, validate: 'bool' = True) -> 'SpacedSweep'` | Run ``periods`` fresh Combines with start days spread evenly over the tape. |
 | `WindowSweep` | `(*args, **kwargs)` | Every window's attempt, plus the rates over them. |
+| `SpacedSweep` | `(*args, **kwargs)` | A requested number of periods, start days spread evenly, overlap allowed. |
 | `WindowResult` | `(*args, **kwargs)` | One window's Combine attempt, resolved on its own merits. |
 
 **Overfitting guards**
@@ -222,11 +282,14 @@ Generated from the live objects — every signature below is real.
 
 | Name | Signature | What it does |
 |---|---|---|
-| `SymbolStrategy.use` | `(self, indicator: 'T') -> 'T'` | Register an indicator: auto-updated on every matching bar and |
+| `SymbolStrategy.use` | `(self, indicator: 'T', *, session: 'Session \| None' = None) -> 'T'` | Register an indicator: auto-updated on every matching bar and |
 | `SymbolStrategy.buy` | `(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'` | Buy this contract (market unless a price kwarg implies otherwise); |
 | `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 +386,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).
 
@@ -386,6 +451,9 @@ Rules here; tables, per-function warmups and the refused-function list in `docs/
   tradeable price. Never route one into grid math without an explicit `round_to_tick`. They are
   float64-precise, not Decimal-exact: deterministic across reruns, but a `Cross` on a Bollinger
   edge can flip on `STDDEV`'s cancellation noise. A band touch is not exact.
+- **`use(ind, session=…)` scopes the DATA; `trade_sessions=` scopes the DECISION.** Two
+  independent switches — see §5.11. Scoping an indicator does not restrict trading, and
+  restricting trading does not starve an indicator.
 - One indicator instance per thread; a parameter sweep gets one per worker.
 
 ### 5.3 Data
@@ -528,12 +596,23 @@ observed trading days and replays each synthetic sequence through a fresh `Combi
 - **`block_length=1` is a footgun.** It degenerates to an i.i.d. resample, destroys the
   losing streaks that actually blow accounts, and will report a pass probability that is far
   too kind. Default is 5.
-- **It refuses to default `horizon_days` when the source run FAILED** — a blown run stops
-  recording days at the breach, so that count is a survival time, not a Combine length.
-  `source_truncated` then flags that the sample is survivorship-biased by construction: the
-  days after the blow-up do not exist, so every figure is conditioned on having survived.
-  Nothing can repair that; do not quote such a result without the caveat.
+- **`horizon_days` defaults to `BILLING_MONTH_DAYS` (21), never the observed day count.** A
+  Combine has no time limit, only a monthly fee, so "one attempt" defaults to one fee cycle —
+  the same unit `EvalEconomics` bills in. The fixed default is also the safety property: a
+  blown run stops recording days at the breach, so its count is a survival time, not a
+  Combine length, and is never used as a horizon. `source_truncated` still flags that such a
+  sample is survivorship-biased by construction — the days after the blow-up do not exist,
+  every figure is conditioned on having survived, and nothing can repair that; do not quote
+  such a result without the caveat.
 - **`provisional` below 30 source days.** Resampling cannot create information.
+- **The point estimate ships with its own cross-examination** (`metrics/confidence.py`).
+  `pass_probability_ci` double-bootstraps the source days themselves — the error bar the
+  day count earns, which the path count never was. `block_length_sensitivity` shows whether
+  the streak assumption is load-bearing. `monte_carlo_by_year` refuses to average a hostile
+  year against a kind one. `crosscheck` compares against `sequential_combines` under a
+  binomial 2×SE null — when they disagree, the disagreement is the finding. Quote a pass
+  probability with its CI, not alone; `mc_confidence` bundles the lot and
+  `report.to_html(path, confidence=..., crosscheck=...)` renders the cards.
 - It cannot invent a regime the tape never contained, and it inherits every uncalibrated
   constant (§5.4). A probability to three decimals from unverified inputs is precise, not
   accurate.
@@ -624,25 +703,70 @@ account.
 - Still your problem on a multi-year tape: **exchange holidays** (~20/year, no calendar
   ships — filter upstream) and the uncalibrated constants (§5.4).
 
+### 5.11 Sessions scope indicator DATA and trading DECISIONS, separately
+
+`ASIA` / `LONDON` / `NEW_YORK` live in `core/sessions.py`; the worked example is
+`examples/session_scoped.py`.
+
+- **The two switches are independent, and conflating them is the bug.**
+  `use(Atr(14), session=NEW_YORK)` restricts which bars that indicator is computed from.
+  `SymbolStrategy(..., trade_sessions=(NEW_YORK,))` restricts when `on_bar` may fire. Indicators
+  advance regardless of `trade_sessions` — an indicator fed only the tradable window develops
+  gaps and computes a different value from the same tape. Both default to today's behaviour, and
+  an unscoped strategy is byte-identical to one written before sessions existed.
+- **Which indicators to scope is a modelling decision, and it is not uniform.** Dispersion
+  measures (`Atr`, `StdDev`, `Rsi`, `Stoch`, `BBands`) describe how much price moves PER BAR, and
+  that is session-dependent: on a 24h feed an `Atr(14)` read at 09:30 ET is computed almost
+  entirely from thin pre-market bars, so it understates NY volatility exactly when stop distance
+  is being sized. Level measures (`Sma`, `Ema`) answer where price IS, and the overnight move is
+  real — an NY-only `Ema` is anchored to yesterday's 16:00 close. **Levels are continuous across
+  sessions; dispersion is not.**
+- **A scoped indicator warms in ITS OWN cadence.** It needs `history_bars` bars *of its session*,
+  so on 5-minute bars an NY-scoped `Sma(30)` spans ~25 trading days against ~7 unscoped. Read
+  `strategy.warm` (per-indicator update counts) or `history_bars_by_session` — never
+  `bars_seen >= history_bars`, which cannot express two cadences and OVERSTATES warmth.
+  `sequential_combines` still SIZES its preload slice from the unscoped `history_bars`, so a
+  scoped strategy will honestly report `fully_warm=False` rather than silently lying.
+- **A `Cross` inherits its inputs' scope** and refuses a conflicting `session=`. Mixed-scope
+  inputs are refused outright: they advance on different bars, so comparing them compares values
+  sampled at unrelated instants.
+- **Sessions are defined in their own timezone, not as fixed ET offsets.** DST comes from the
+  IANA database, so nothing rots — London and New York switch on different dates, and the London
+  window really is 04:00 ET rather than 03:00 for ~3 weeks each spring and ~1 each autumn. A
+  fixed ET block is still one line: `Session("LONDON_ET", ET, time(3), time(11))`.
+- **Session membership is a DIFFERENT axis from `trading_day_of()`.** Asia sits after the 18:00
+  ET rollover, so its bars belong to the NEXT trading day. Membership is tested on `ts_event`
+  (the bar's OPEN) over a half-open `[start, end)` window, so the 09:29→09:30 bar — every print
+  of it pre-market — is not New York.
+- **`trade_sessions` only narrows what THIS strategy does.** It never widens what the venue
+  permits: the 16:10 ET flatten and the 16:10–18:00 no-trade window apply either way.
+- **You need 24h data.** The shipped `data/sample_mnq_1m.csv` is RTH-only (390 bars/day,
+  09:30–15:59 ET) and contains no Asia or London bars, so nothing session-scoped is observable on
+  it. For synthetic bars pass `synthetic_bars(..., hours="globex")`; the default `"rth"` mode is
+  the New York session and nothing else.
+- **Not built: per-session performance attribution.** Nothing in `SummaryStats` splits P&L by
+  session, so scoping is currently a modelling choice you make, not one the report scores.
+
 ## 6. The end-to-end workflow
 
 What using this framework actually looks like, in the order you do it:
 
 ```python
 from topstep_backtest import AccountSize, Backtest
-from topstep_backtest.metrics import monte_carlo
-from topstep_backtest.rules.kernel import Verdict
+from topstep_backtest.metrics import crosscheck, mc_confidence, sequential_combines
 from topstep_backtest.rules.params import combine_params
 
-# 1. Write the strategy (§2), then run ONE backtest.
-report = Backtest(bars, MyStrategy(CONTRACT), account=AccountSize.S50K).run()
+# 1. Write the strategy (§2), then run ONE backtest — recorded, so the replay
+#    tab can show intent against execution.
+report = Backtest(bars, MyStrategy(CONTRACT), account=AccountSize.S50K, record=True).run()
 print(report)  # verdict, day trail, four statistics blocks
 
 # 2. Sanity-check the wiring BEFORE reading any number.
 assert not report.result.rejections  # zero trades + rejections = broken wiring (§5.5)
 assert report.bars_gated != len(bars)  # warmup longer than your data
 
-# 3. Read the run, minding the basis (§5.6).
+# 3. Read the run, minding the basis (§5.6) — and step the replay tab to each
+#    entry: the bracket where you meant it, the notes matching the fills.
 s = report.stats
 if s.provisional:
     ...  # under 200 closes: estimates, not findings
@@ -652,16 +776,19 @@ s.drawdown.eod_trailing  # Topstep's actual MLL mechanic
 s.drawdown.min_floor_headroom  # closest the account came to death
 s.daily.p05  # the bad day to size against
 
-# 4. Stop trusting one sample. A FAILED run needs an explicit horizon (§5.7).
-horizon = None if report.result.verdict is not Verdict.FAILED else 40
-mc = monte_carlo(
-    report.result, params=combine_params(AccountSize.S50K), paths=3000, horizon_days=horizon, seed=7
-)
+# 4. Stop trusting one sample — real attempts first, resampled ones second.
+sweep = sequential_combines(bars, lambda: MyStrategy(CONTRACT), window_days=21)
+c = mc_confidence(report.result, params=combine_params(AccountSize.S50K), seed=7)
+check = crosscheck(c.mc, sweep)  # same billing-month horizon on both sides (§5.7)
 
-# 5. Act on the AUTOPSY, not the headline.
+# 5. Act on the AUTOPSY, and quote the CI, never the bare point (§5.7).
 #    mll_breach          -> resize
 #    consistency_blocked -> throttle the outsized day; the edge is fine
 #    target_not_reached  -> the edge is too slow; nothing risk-side helps
+c.ci.p05, c.ci.p95  # the error bar the source-day count earns
+c.sensitivity.spread  # wide = the streak assumption is doing the work
+check.divergent  # bootstrap vs real windows: disagreement is the finding
+report.to_html("run.html", confidence=c, crosscheck=check)  # the cards, archived
 
 # 6. Was it an edge, or did you search until something looked good? The trial
 #    count must be RECORDED — a remembered one is always too low, because the
@@ -674,7 +801,7 @@ dsr.expected_max_sharpe > dsr.sharpe  # the search alone explains the result
 
 # 7. Is the attempt worth its price? Every figure is yours; none is baked in.
 ev = evaluate_ev(
-    mc,
+    c.mc,
     economics=EvalEconomics(
         monthly_fee=Decimal("149"), pass_value=Decimal("2000"), reset_fee=Decimal("99")
     ),
@@ -692,9 +819,10 @@ that. **EV's `pass_value` is an assumption you supply and this package cannot ch
 dominates the answer, so quote `breakeven_pass_value` ("a pass must be worth at least $X")
 rather than `ev` unless you can defend the input.
 
-Runnable end to end: `examples/run_combine.py` (steps 1–3) and
-`examples/run_montecarlo.py` (steps 4–5, at two position sizes so the autopsy visibly
-discriminates). `docs/TUTORIAL_EMA_CROSSOVER.md` walks all of it line by line.
+Runnable end to end: `examples/run_combine.py` (steps 1–3), `examples/run_windows.py` and
+`examples/run_montecarlo.py` (steps 4–5, the latter at two position sizes so the autopsy
+visibly discriminates). `docs/TUTORIAL_EMA_CROSSOVER.md` walks all of it line by line, and
+`website/workflow.md` is the narrative version with the gate each stage must pass.
 
 ## 7. What `Backtest()` refuses, and what to use instead
 
@@ -727,9 +855,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 +932,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
@@ -810,8 +940,8 @@ moving one toward optimism is a probe to report next to the baseline, not a new
 `docs/ROADMAP.md` is the authority. These names appear in older notes and other frameworks and
 **do not exist here**: `LiveBroker`, `RecordingLiveBroker`, `DataEngine`, `TrailingMaxLossLimit`,
 `prob_fill_on_limit` (the real field is `BarFillConfig.fill_limit_on_touch`). Also absent: a
-Parquet/Arrow data catalog, multi-timeframe resampling, a MessageBus, per-year / per-regime
-breakdowns, higher fill tiers, an XFA rule set, and any holiday calendar.
+Parquet/Arrow data catalog, multi-timeframe resampling, a MessageBus, per-year / per-regime /
+per-session breakdowns (§5.11), higher fill tiers, an XFA rule set, and any holiday calendar.
 
 **Do** write code against these — they used to be on the list above and now ship: Monte-Carlo
 (§5.7), `optimize()` and the overfitting guards (§5.9), the sequential-Combine sweep (§5.8),

{topstep_backtest-0.2.3 → topstep_backtest-0.4.0}/CHANGELOG.md

@@ -4,7 +4,239 @@ 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.4.0] — 2026-08-25
+
+A minor: new features throughout. One behavioural default changed — the Monte-Carlo
+horizon now defaults to one billing month rather than the observed day count.
+
+### Added
+
+- **Regional sessions** (`core/sessions.py`: `Session`, `ASIA`, `LONDON`, `NEW_YORK`) and the two
+  independent switches that use them. `use(indicator, session=...)` scopes an indicator's INPUT
+  DATA; `SymbolStrategy(trade_sessions=...)` scopes DECISIONS. Keeping them separate is the
+  whole feature — a strategy can hold a continuous 24h `Ema` beside an NY-only `Atr` and still
+  trade only New York. Indicators advance regardless of `trade_sessions`, because starving one
+  outside the tradable window would leave it with gaps and a different value than the same
+  indicator on the same tape. Both default to today's behaviour and an unscoped run is
+  byte-identical.
+
+  Why you would scope at all: dispersion measures (`Atr`, `StdDev`, `Rsi`) describe how much
+  price moves *per bar*, and that is session-dependent — on 24h bars an `Atr(14)` read at 09:30
+  ET is computed almost entirely from thin pre-market bars, understating NY volatility exactly
+  when stop distance is being sized. Level measures (`Sma`, `Ema`) answer where price *is*, and
+  the overnight move is real: an NY-only `Ema` is anchored to yesterday's 16:00 close and blind
+  to a London repricing. Levels are continuous across sessions; dispersion is not.
+
+  **Sessions are defined in their own local timezone**, not as fixed ET offsets, so DST comes
+  from the IANA database and there is no hand-maintained table to rot — the same reasoning that
+  dropped the exchange calendar. London and New York switch on different dates, so the London
+  window really is 04:00 ET rather than 03:00 for about three weeks a year, and the tests assert
+  that against concrete 2026 dates. A fixed-ET block remains one line away
+  (`Session("LONDON_ET", ET, time(3), time(11))`), midnight-wrapping included.
+
+  Session membership is a **different axis** from `trading_day_of()`: Asia sits after the 18:00
+  ET rollover, so its bars belong to the *next* trading day. Membership is tested on `ts_event`
+  (the bar's open) over a half-open window, so the 09:29->09:30 bar — every print of it
+  pre-market — is not New York.
+
+- `SymbolStrategy.warm`, `.registrations`, `.history_bars_by_session`, `.bars_out_of_session`,
+  `.bars_seen`, `.in_trade_session()` — the diagnostics scoping makes necessary. A scoped
+  indicator warms in its OWN cadence, so it needs `history_bars` bars *of its session*: on
+  5-minute bars an NY-scoped `Sma(30)` spans ~25 trading days against ~7 for the same indicator
+  on a 24h feed. `warm` counts each indicator's own updates, which a single bar count cannot
+  express, and `sequential_combines` now asks the strategy rather than comparing counts — the
+  old `preload >= needed` silently OVERSTATED warmth for a scoped indicator.
+
+- `synthetic_bars(hours="globex")` — the full 23-hour electronic session (18:00 ET previous
+  calendar day to 17:00 ET), reusing the canonical open from `core/time.py`. The default
+  `"rth"` mode is unchanged. Without this nothing session-scoped is testable: the shipped
+  `data/sample_mnq_1m.csv` is RTH-only (exactly 390 bars/day, 09:30-15:59 ET) and contains no
+  Asia or London bars at all.
+
+- A `Cross` now **inherits its inputs' data scope** and refuses a conflicting one, alongside the
+  existing refusal of unregistered inputs. Crossing a 24h `Ema` against an NY-scoped `Ema`
+  compares values sampled on unrelated cadences; leaving the `Cross` continuous over scoped
+  inputs would have it re-read unchanged values on most bars. Both were silent before.
+
+- **`metrics.spaced_combines` — pick how many Combine attempts to simulate.**
+  Where `sequential_combines` lets the tape dictate the attempt count (disjoint windows),
+  the new sweep takes `periods` and `window_days` and spreads that many start days evenly
+  across the tape, overlapping as much as the arithmetic requires — 100 days, 10 periods
+  of 40 days starts an attempt roughly every week. Each period is still a completely fresh
+  Combine (same shared implementation: day-aligned slicing, prewarmed indicators, the
+  kernel's own verdict, `classify_failure` attribution), so the sweep measures how much
+  passing depends on *when* the attempt starts. Because overlapping periods are not
+  independent samples, the result carries `effective_independent_windows`,
+  `stride_days` and `overlap_fraction` alongside its rates, and asking for more periods
+  than the tape has distinct start days is refused rather than replaying identical
+  windows as new observations. `examples/run_spaced.py` renders a sweep as a text
+  report — the rates with their effective-sample caveat in the header, then one line
+  per period in start order so start-date sensitivity is visible at a glance.
+
+- **An HTML tearsheet for sweeps.** `sweep.to_html(path)` / `sweep.show()` on both
+  `WindowSweep` and `SpacedSweep` (or `tearsheet.render_sweep_html`) render one
+  self-contained page: a calendar timeline with each attempt drawn over its actual
+  dates and stacked into lanes where they overlap — the reason overlapping attempts
+  are not independent samples made visible rather than footnoted — the outcome
+  autopsy as a stacked bar with each failure mode's prescription, every attempt's
+  cumulative P&L overlaid from $0, a closest-approach-to-the-MLL-floor strip (a pass
+  with $40 of headroom looks identical to a robust one in the pass rate; not here),
+  and a sortable per-attempt table with P&L sparklines, all hover-linked. To feed the
+  charts, `WindowResult` now carries `daily_pnl` (and a `cumulative_pnl` property),
+  the same per-day series walk-forward's trials keep. No charting library and no
+  embedded JSON: the charts are SVG generated in Python, so the render stays a pure
+  byte-identical function of the frozen sweep data, and the evidence caveat is
+  stamped in the page header where a screenshot cannot shed it.
+
+- **Confidence instruments for the Monte-Carlo pass probability**
+  (`metrics/confidence.py`). The point estimate's *simulation* error was never the real
+  uncertainty; these quantify what is. `pass_probability_ci` double-bootstraps the observed
+  day set itself and reports a 5th–95th percentile band — the error bar the source-day
+  count earns (a 65% from 500 days and a 65% from 40 now read differently).
+  `block_length_sensitivity` re-runs the estimate across block lengths and reports the
+  spread: wide means the streak-clustering assumption is doing the work.
+  `monte_carlo_by_year` stratifies by calendar year so a hostile year is never averaged
+  against a kind one — the spread across strata is the error bar non-stationarity imposes.
+  `crosscheck` forces the bootstrap and `sequential_combines` (opposite biases, shared
+  `classify_failure` on purpose) to answer side by side, flagging any outcome where the
+  real windows sit outside 2×SE of what the bootstrap's own probability would produce;
+  when they disagree, the disagreement is the finding. `mc_confidence` bundles the first
+  three, and every estimate runs through the same `monte_carlo_from_blocks` core as the
+  number it qualifies. All deterministic per seed, like everything else in `metrics/`.
+- **Monte-Carlo cards on the tearsheet.** `report.to_html(path, confidence=...,
+  crosscheck=...)` (and `show` / `to_timestamped_html`) render the estimate with its CI,
+  the block-sensitivity row, the per-year strata, and the bootstrap-vs-windows card.
+  Caller-computed on purpose: writing a file never triggers thousands of simulations as a
+  side effect, and the render stays a pure, byte-identical function of its inputs.
+- **The workflow, documented** (`website/workflow.md`, on the site nav as "The workflow").
+  The stages in the order the questions become answerable — envelope, data, strategy, one
+  recorded run, real attempts, the distribution with its confidence, the search guards,
+  the price — each ending with the gate that must pass before the next stage's number
+  means anything. `AGENTS.md` §6 is the code-first version and now walks the same loop
+  (recorded run, `sequential_combines`, `mc_confidence` + `crosscheck`, guards, EV).
+
+- **A native loader for databento-data-playground Parquet exports.**
+  `topstep_backtest.data.loaders.load_bars(path)` reads an export produced by that project's
+  `convert.py` and returns `(bars, spec, meta)` ready for `Backtest(...)`. The product, bar
+  span and timestamp stamping are read from the file's embedded Parquet metadata rather than
+  passed in — each is a silent corruption when guessed — and the file's copy of the
+  instrument economics is cross-checked against the engine's `InstrumentSpec`, failing loudly
+  on any mismatch instead of picking one. Files without the metadata blob are refused.
+  Requires the existing `[data]` extra (pandas + pyarrow); nothing new to install.
+  `examples/run_real_data.py` auto-detects such exports and loads them with no declaration
+  flags (and refuses the flags on one — re-declaring what the file states is the
+  contradiction they exist to prevent), and the module joins the site's API reference and
+  quickstart.
+
+### Changed
+
+- **The Monte-Carlo horizon defaults to one billing month** (`BILLING_MONTH_DAYS = 21`),
+  not the observed day count. A Combine has no time limit, only a monthly fee, so "one
+  attempt" defaults to one fee cycle — the same unit `EvalEconomics` bills in (its
+  `trading_days_per_month` default now *is* this constant). The fixed default also
+  retires the guard that made `horizon_days` mandatory for a blown source run: the old
+  hazard was defaulting to a survival time, and the new default cannot. A failed run
+  still reports `source_truncated`, and the survivorship-bias caveat stands unchanged.
+- `sample_day_path`, `nearest_rank`, and `monte_carlo_from_blocks` are module-level
+  names in `metrics/montecarlo.py` (previously underscore-private) so the confidence
+  instruments run through the identical core; they remain outside `__all__`.
+- **The replay cockpit is easier to read.** The running-stats panel no longer stacks all
+  ~50 rows: snapshots are regrouped into by-type cards — *status*, *trades (gross)*,
+  *round trips (net)*, *risk & quant*, *daily P&L* — shown one at a time behind filter
+  chips, with a `•` on any chip whose hidden card the newest snapshot moved. The values are
+  the same rows the results tab renders, relocated rather than rebuilt (a stat missing from
+  the regrouping map fails loudly instead of silently vanishing from the replay). The event
+  log moved from the cramped right column to a full-width strip under the charts — one
+  event per line, heading and kind filters on one row — and the panel text was tightened
+  throughout. Both tabs' price charts also gained a marker legend (entry/exit arrows, and
+  in the replay the cross fires and the working stop/target/avg-entry price lines), so the
+  glyphs on the tape no longer require guessing.
+
+## [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
 
@@ -338,4 +570,6 @@ 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.4.0]: https://pypi.org/project/topstep-backtest/0.4.0/
+[0.3.0]: https://pypi.org/project/topstep-backtest/0.3.0/
 [0.1.0]: https://pypi.org/project/topstep-backtest/0.1.0/