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

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

@@ -45,3 +45,5 @@ site/
 # 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.3.0 → topstep_backtest-0.4.0}/AGENTS.md

@@ -127,7 +127,7 @@ 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**
 
@@ -144,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**
 
@@ -158,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 |
@@ -170,7 +185,8 @@ Generated from the live objects — every signature below is real.
 
 | Name | Signature | What it does |
 |---|---|---|
-| `render_html` | `(report: 'Report', *, replay: 'ReplaySpec' = 'auto') -> '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**
 
@@ -199,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**
@@ -249,7 +282,7 @@ 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``. |
@@ -418,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
@@ -560,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.
@@ -656,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
@@ -684,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
@@ -706,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")
     ),
@@ -724,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
 
@@ -844,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.3.0 → topstep_backtest-0.4.0}/CHANGELOG.md

@@ -4,6 +4,154 @@ All notable changes to this project are documented here. This project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html). While the version is
 below 1.0, minor releases may contain breaking changes.
 
+## [0.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.
@@ -422,5 +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/

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: topstep-backtest
-Version: 0.3.0
+Version: 0.4.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
@@ -84,6 +84,22 @@ indicator formula, so there is no second implementation to drift from the refere
 `Cross` is the deliberate exception — TA-Lib has no crossover primitive, so it is a
 framework helper that compares two TA-Lib outputs rather than computing anything.
 
+**Sessions are two independent switches.** On a 24h tape you can scope each indicator's input
+data and, separately, restrict when the strategy may trade:
+
+```python
+super().__init__(contract_id, trade_sessions=(NEW_YORK,))  # trade New York only
+self.trend = self.use(Ema(50))  # ...but see the whole tape
+self.atr = self.use(Atr(14), session=NEW_YORK)  # ...while this sees only NY
+```
+
+The `Ema` keeps consuming Asia and London — an indicator fed only the tradable window would
+develop gaps — while every decision happens in New York. Which indicators to scope is a
+modelling choice with a rule behind it: *levels are continuous across sessions, dispersion is
+not*. `ASIA`/`LONDON`/`NEW_YORK` are defined in their own timezones, so daylight saving comes
+from the IANA database rather than a table that rots. See
+[`examples/session_scoped.py`](examples/session_scoped.py).
+
 ## Install
 
 ```bash
@@ -184,8 +200,9 @@ cannot disagree. For a sheet from *every* run without naming a file each time,
 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
+replay cockpit that fills the window — its own charts beside the settled state and the
+running stats (by-type cards behind filter chips), the event log across the bottom, 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
@@ -231,6 +248,15 @@ imply three different fixes:
 | `consistency_blocked` | money made in too few days — throttle the outsized day; the edge is fine |
 | `target_not_reached` | the edge is too slow for the window — nothing risk-side helps |
 
+The horizon defaults to one billing month (21 sessions) — a Combine has no time limit, only
+a monthly fee, so "one attempt" means one fee cycle, the same unit `evaluate_ev` bills in.
+And never quote the pass probability alone: `metrics.confidence.mc_confidence` attaches the
+error bar the *source-day count* earns (a double-bootstrap CI — the path count was never the
+real uncertainty), a block-length sensitivity row, and per-year strata, while
+`metrics.confidence.crosscheck` compares the bootstrap against `sequential_combines`' real
+windows — when the two disagree, the disagreement is the finding. The whole bundle renders
+on the tearsheet via `report.to_html(path, confidence=..., crosscheck=...)`.
+
 ```bash
 uv run python examples/run_montecarlo.py   # the same edge at two sizes, failing two ways
 ```
@@ -253,6 +279,10 @@ reruns — but read these before trusting a number:
   `metrics/economics.py`), but none of them escapes your sample: the Monte-Carlo resamples a
   strategy's own observed days, so it cannot invent a market regime your tape never contained
   and will understate tail risk on a short or single-regime sample.
+- **No per-year, per-regime or per-session performance breakdown.** Sessions scope which bars
+  an indicator is computed from and when a strategy may trade, but nothing in `SummaryStats`
+  splits P&L by session, so a scoping choice is one you make on reasoning rather than one the
+  report scores for you.
 - **No exchange holiday calendar ships with this package.** Bars on market holidays and
   past early-close halts are not detected, flagged or filtered anywhere — filter them
   upstream. (A built-in calendar was removed in 0.1.0: it disagreed with CME on several
@@ -286,6 +316,7 @@ uv run pytest && uv run ruff check . && uv run ruff format --check . && uv run p
 uv run python scripts/gen_api_surface.py --check   # AGENTS.md §3 must not be stale
 uv run python examples/run_combine.py              # end-to-end combine verdict
 uv run python examples/run_montecarlo.py           # outcome distribution + autopsy
+uv run python examples/session_scoped.py           # session-scoped indicators + trade gate
 ```
 
 Those checks are the gate: CI runs all of them on Python 3.12/3.13/3.14, then installs the
@@ -314,23 +345,29 @@ environment. There is no public issue tracker.
 
 - **`docs/TUTORIAL_EMA_CROSSOVER.md` — start here**: one strategy end to end, raw candles
   to Combine verdict.
+- `website/workflow.md` — **the workflow**: the stages in the order the questions become
+  answerable — data, mechanics, real attempts, the distribution with its confidence, the
+  search guards, the price — and the gate each must pass before the next number means
+  anything.
 - `website/results.md` — **reading the report**: what every figure means, what basis it is
   on, which ones mislead alone, and what this framework deliberately does *not* report.
 - `AGENTS.md` — dense reference for *using* the framework: strategy dialect, module map, the
-  invariants you must not break, and **§6, the end-to-end workflow** (run → check the wiring
-  → read the run minding each metric's basis → Monte-Carlo → act on the autopsy).
+  invariants you must not break, and **§6, the end-to-end workflow** (run recorded → check
+  the wiring → read the run minding each metric's basis → real windows + Monte-Carlo with
+  its CI → act on the autopsy → deflate the search → price the attempt).
 - `docs/INDICATORS.md` — the TA-Lib indicator surface, wrapper by wrapper.
 - `docs/topstep-rules.md` — the rulebook being enforced, with sources, confidence levels,
   and a verify-before-trusting checklist.
 - `docs/DESIGN.md` — architecture contract, for *modifying* the framework.
 - `docs/ROADMAP.md` — what is built, partial, and not started. Next: **live adapter +
-  calibration** → per-year / per-regime breakdowns → L1/L2/MBO fill tiers; funded-account
-  (XFA) modeling is deliberately parked.
+  calibration** → per-regime (non-calendar) breakdowns → L1/L2/MBO fill tiers;
+  funded-account (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_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`,
+  independent Combine attempts), `run_spaced.py` (a chosen number of attempts, start days
+  spread evenly, overlap allowed), `ema_cross.py`, `sma_cross.py`, `talib_macd.py`,
   `hand_wired.py` (what the facade assembles).
 
 ## Stack