quantbt-engine 1.0.7__tar.gz → 1.0.9__tar.gz

{quantbt_engine-1.0.7 → quantbt_engine-1.0.9}/CHANGELOG.md

@@ -2,6 +2,48 @@
 
 All notable changes to `quantbt-engine` are documented here.
 
+## [1.0.9] - 2026-08-21
+
+### Added
+
+- Direct PyPI discovery and installation guidance in the repository README.
+- Release-preparation guidance for the governed Rust-first routes, exact
+  installed-wheel certification, and the matching core/native compatibility
+  contract.
+
+### Changed
+
+- Promoted the bounded Rust-first public policy for certified static command
+  tapes, Native Strategy IR, batch, and causal-fold workloads while preserving
+  Python authority for callbacks, reactive strategies, generic portfolio,
+  basket, arbitrage, and options routes.
+- Updated the core product registry to the `1.0.9` release line. The staged
+  `quantbt-native` companion remains unpublished and capability-gated.
+
+### Verification
+
+- Source-mirror, generated-product-contract, documentation-link, build, and
+  installed-wheel release checks are required from the final tagged commit.
+
+## [1.0.8] - 2026-08-12
+
+### Changed
+
+- Added strict nested causal retraining for
+  `mode_1_decay + optimization_schedule="per_fold_causal"`. Mode 1 decay now
+  uses inner IS-only folds while each outer OOS segment remains untouched until
+  its parameters are frozen.
+- Added explicit chronological validation metadata so consumers can distinguish
+  retrospective global calibration, selection-adjusted OOS, and strict outer
+  OOS evaluation without breaking legacy result fields.
+- Added a bounded-RSS release test runner that executes deterministic pytest
+  shards in fresh processes; CI and publish workflows use the same selection.
+
+### Verification
+
+- Root/source mirror, prepared/reference WFO parity, nested-fold causality,
+  and the full non-real-data release suite passed before this version bump.
+
 ## [1.0.7] - 2026-08-04
 
 This is the first independently installable core package release line.

{quantbt_engine-1.0.7/src/quantbt_engine.egg-info → quantbt_engine-1.0.9}/PKG-INFO

@@ -1,10 +1,11 @@
 Metadata-Version: 2.4
 Name: quantbt-engine
-Version: 1.0.7
+Version: 1.0.9
 Summary: Transparent, high-performance quantitative backtesting engine
 Author-email: Vu Cong Minh <vugioan11022002@gmail.com>
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/BobbyAxerol/quantbt
+Project-URL: PyPI, https://pypi.org/project/quantbt-engine/
 Project-URL: Repository, https://github.com/BobbyAxerol/quantbt
 Project-URL: Issues, https://github.com/BobbyAxerol/quantbt/issues
 Project-URL: Documentation, https://github.com/BobbyAxerol/quantbt/tree/main/docs
@@ -51,6 +52,7 @@ Dynamic: license-file
 # QuantBT
 
 ![Python](https://img.shields.io/badge/python-3.11%2B-blue)
+[![PyPI](https://img.shields.io/pypi/v/quantbt-engine.svg?label=PyPI)](https://pypi.org/project/quantbt-engine/)
 ![Numba](https://img.shields.io/badge/core-numba-00A86B)
 ![Backtesting](https://img.shields.io/badge/backtesting-vectorized%20%7C%20event--driven-black)
 ![Nautilus](https://img.shields.io/badge/nautilus-optional-6f42c1)
@@ -68,6 +70,10 @@ The goal is simple: make alpha research fast enough for iteration, strict
 enough for institutional-style review, and readable enough that stakeholders can
 audit how a result was produced.
 
+QuantBT is published on [PyPI as `quantbt-engine`](https://pypi.org/project/quantbt-engine/).
+Install the current public release with `pip install --upgrade quantbt-engine`;
+the import remains `from quantbt import QuantBTEndpoint`.
+
 Current portfolio status: `native_portfolio` is the default multi-symbol
 backend. It supports long/short, market-neutral, directional, equal-weight,
 risk-parity, and beta-neutral portfolio modes, with live-equity sizing and
@@ -79,7 +85,7 @@ historical reproduction.
 - One public API for notebooks, services, portfolio research, and validation.
 - Native vectorized engines for fast sweeps and large parameter grids.
 - Native event-driven engines for market/limit orders, fills, baskets, and
-  arbitrage package execution.
+  package execution, with Rust auto-promotion limited to certified workloads.
 - Prepared service contexts for repeated signal/portfolio replays on the same
   market tape without re-normalizing pandas data each run.
 - Native portfolio engine with target weights, target notionals, target units,
@@ -115,6 +121,7 @@ bt = QuantBTEndpoint.event_driven(
     input_mode="strategy",   # strategy | orders
     profile="research",      # research | optimize | audit
     backend="auto",          # auto | python | rust
+    execution_contract="event_lifecycle_v3_next_open",
     initial_capital=20_000,
     leverage=5,
     fee_rate=0.0005,          # one-way fee per fill
@@ -133,6 +140,21 @@ event artifacts. For an upstream order planner, switch to
 backend follows the release policy; `rust` is an explicit request for the
 optional capability-gated native wheel.
 
+An arbitrary `strategy=...` callback remains a Python-authoritative route,
+including when `backend="auto"` and a local native wheel is installed. The
+current automatic Rust routes are a pre-built static V2/V3 command tape with
+at least 10,000 bars, or a bounded `NativeStrategyIR` request with at least
+2,000 bars. Inspect `result.metadata["native_event_promotion_v1"]` to see the
+resolved backend, threshold, policy rule, and fallback reason for every run.
+
+The compatibility default is the frozen
+`event_lifecycle_v2_next_bar_close` behavior. Select
+`event_lifecycle_v3_next_open` for real next-open market fills, favorable
+limit-gap improvement, adverse stop-gap execution, and conservative flagged
+stop-limit ambiguity. V3 requires an `open` column and is parity-tested across
+the Python and Rust backends. The machine-readable registry and audit fields
+are documented in [Native Event Contract Registry](docs/contracts/contract_registry.md).
+
 The strategy owns signal generation and look-ahead control. QuantBT owns the
 causal order lifecycle and accounting. Advanced users can still call
 `native_event_strategy(...)` or `native_event_lifecycle(...)` directly when a
@@ -218,6 +240,21 @@ tape. Normal `.backtest(...)` remains defensive and backward-compatible.
 Cython/C++ remains deferred because the larger benchmark still points to
 facade/report overhead rather than pure Numba kernels.
 
+Latest Phase 49B WFO benchmark (1,000 daily bars, identical seeds, folds,
+trials, strategies, account settings, and accounting kernels):
+
+| WFO workload | Phase 49A reference | Phase 49B prepared/scalar | Speedup | Parity |
+|---|---:|---:|---:|---|
+| Portfolio global, 1 study x 16 trials | 0.386s | 0.330s | 1.17x | exact |
+| Single-symbol causal, 6 studies x 16 trials | 4.051s | 1.781s | 2.27x | exact |
+
+Phase 49B prepares aligned WFO fold state once, scores trials directly from
+accounting arrays, and compacts completed Optuna ledgers. It does not cache user
+strategy signals or alter objectives. The isolated warm peak-RSS difference was
+within +/-0.15%, so the result is reported as an RSS plateau rather than a memory
+reduction. Reproduce it with
+`python benchmarks/run_phase49b_wfo_performance.py --rows 1000 --trials 16`.
+
 Latest Phase 31 intrabar execution benchmark:
 
 | Route | Workload | Runtime | Throughput | Ratio | Parity |
@@ -255,7 +292,70 @@ selection semantics inside `walkforward.py`. Read
 `benchmarks/results/optimization_overhead.md` for signal, intrabar, portfolio,
 arbitrage/grid/options fallback examples and benchmark details.
 
-### Phase 46F package and dual-backend release evidence
+### Current governed Rust routes and benchmark evidence
+
+Rust is execution-authoritative only where the public request, accounting
+contract, installed-wheel parity corpus, and promotion policy have all been
+certified. The generated Stage-B policy has this deliberately narrow scope:
+
+| Route | Rust behavior with a matching local companion | Public default elsewhere |
+|---|---|---|
+| Static V2/V3 `OrderCommand` tape | `auto` at 10,000+ bars | Python |
+| Bounded Native Strategy IR, batch, causal-fold scorer | `auto` at 2,000+ bars | Python |
+| `run_portfolio_target_market(...)` | explicit Rust helper | no generic endpoint promotion |
+| `run_atomic_package_market(...)` | explicit Rust helper | no generic endpoint promotion |
+| Python callback/reactive, generic portfolio/basket/arbitrage/options | not promoted | Python |
+
+The bounded Rust strategy IR covers precomputed signal targets, structural
+Grid levels, periodic DCA, and fixed bracket/OCO transitions. Python callbacks,
+reactive strategies, and generic portfolio/package/arbitrage execution remain
+Python compatibility routes by design.
+
+Phase 54B.3 also certifies two intentionally explicit Rust helpers,
+`run_portfolio_target_market(...)` and `run_atomic_package_market(...)`, for
+linear quote-settled gross-cross `target_units` and one ordered same-bar
+all-or-none market package respectively. They do not change generic endpoint
+routing or claim venue-native multi-leg execution; the bounded contract,
+parity corpus, and benchmark evidence are documented in
+[`docs/native_event_rust_full_contract.md`](docs/native_event_rust_full_contract.md).
+On the governed 2,000-bar x 8-symbol fixture, their Rust score paths measured
+3.594 ms (556,551 bars/s) for target units and 3.512 ms (569,514 bars/s) for
+the atomic package, versus Python event-oracle score paths of 33.493 ms and
+19.735 ms respectively. These are bounded direct-route measurements; audit
+report adaptation is intentionally timed and reported separately.
+
+The local five-repeat public-route evidence below passed exact Python/Rust
+canonical-trace and accounting parity before timing. It is deliberately not a
+universal Rust speed claim: static public facade time is dominated by common
+Python preparation/report adaptation, while typed IR score and shared batch
+avoid those per-scenario costs.
+
+| Workload | Bars | Rust median | Rust throughput | Python median | Python throughput |
+|---|---:|---:|---:|---:|---:|
+| Static public compact | 10,000 | 63.612 ms | 157,203 bars/s | 53.606 ms | 186,545 bars/s |
+| Static public audit | 10,000 | 6.024 s | 1,660 bars/s | 5.924 s | 1,688 bars/s |
+| Native IR score | 2,000 | 0.741 ms | 2.70M bars/s | 31.565 ms | 63,361 bars/s |
+| Native IR batch, 64 scenarios | 128,000 | 11.379 ms | 11.25M bars/s | - | - |
+| Native IR causal fold, 64 scenarios | 64,000 | 7.386 ms | 8.67M bars/s | - | - |
+
+The Rust IR score has one boundary call, zero Python callbacks, and no audit
+replay. Batch/fold execution has one boundary call and zero prepared-market
+copies per scenario; its repeated-run RSS delta was 8-16 KiB on this host. An
+audit result is intentionally a cold reporting path: its typed Rust output is
+adapted to the normal `BacktestResultV2` without rerunning execution. Full
+evidence is in
+[`phase54b2/public_routes.md`](benchmarks/native_event/results/phase54b2/public_routes.md)
+and the support boundary is in
+[`docs/native_strategy_ir.md`](docs/native_strategy_ir.md).
+
+Phase 54B.4 adds an installed-wheel release gate, rather than a new speed
+claim. It proves clean core-only fallback, exact core/native-pair handshake,
+promotion decisions, and Python/Rust accounting parity for every governed
+route. The public `quantbt-engine` wheel remains core-only until a separately
+approved native wheel release; see the
+[native release handoff](docs/migration/native_release_handoff.md).
+
+### Historical Phase 46F package and dual-backend release evidence
 
 The core distribution is packaged as `quantbt-engine` and imports as
 `quantbt`. Its release gate is independent from the optional experimental Rust
@@ -263,8 +363,8 @@ wheel:
 
 | Release artifact | Current status | Backend policy |
 |---|---|---|
-| `quantbt-engine==1.0.7` wheel/sdist | release-ready after local/TestPyPI approval | Python canonical; all existing endpoints remain available |
-| `quantbt-native` PyO3 wheel | experimental, not published | explicit `native_backend="rust"` only |
+| `quantbt-engine` wheel/sdist | published on PyPI | Python canonical; all existing endpoints remain available |
+| `quantbt-native` PyO3 wheel | staged, not published | local Stage-B `auto` only for certified static/IR/batch rows |
 | `quantbt-engine[native]` | intentionally empty | no dependency is advertised before native certification |
 
 The committed Phase 46F rerun compares the same prepared static tape and keeps
@@ -330,7 +430,7 @@ Raw Phase 47D artifacts are kept under
 
 ### Phase 48F final release handoff
 
-The core `quantbt-engine` 1.0.7 artifact gate is now implemented locally and
+The core `quantbt-engine` 1.0.8 artifact gate is now implemented locally and
 in the release workflows: exact version/ref validation, wheel and sdist
 `twine check`, archive allowlist and secret scan, clean import plus `pip check`,
 and a SHA256 release manifest. The TestPyPI workflow is manual and OIDC
@@ -372,7 +472,10 @@ The release workflow is documented in
 [`docs/release_packaging.md`](docs/release_packaging.md): build and inspect
 wheel/sdist, run clean-install and `pip check`, publish an RC to TestPyPI with
 OIDC, then publish the final core package through the protected PyPI
-environment. The exact handoff fields and artifact-hash procedure are in
+environment. The native companion scope, rollback controls, and installed-wheel
+certification handoff are in
+[`docs/migration/native_release_handoff.md`](docs/migration/native_release_handoff.md).
+The exact handoff fields and artifact-hash procedure are in
 [`docs/testpypi_release_checklist.md`](docs/testpypi_release_checklist.md).
 No long-lived token is required. Native optimization remains an
 open, domain-preserving roadmap for portfolio, arbitrage, options, vectorized,
@@ -440,8 +543,10 @@ Phase 48E also reduced the static explicit Rust score to `0.000302s`
 scalar Rust output contract and prepared command-tape reuse, so they are
 reported separately from callback execution. Rust and Python fingerprints,
 fees, positions, fills, events, rejection counters, and final equity passed.
-`backend="auto"` remains Python and `[native]` remains empty until the public
-`quantbt-native` wheel matrix is clean-install certified.
+At Phase 48E this historical benchmark had `auto` pinned to Python. The later
+Phase 54B.2 local Stage-B policy promotes only the certified static/IR/batch
+rows documented above; `[native]` remains empty until a public native-wheel
+matrix is clean-install certified.
 
 ### Phase 48E.1 native production-closure evidence
 
@@ -472,9 +577,10 @@ facade; it is not a universal Rust speed claim.
 
 Phase 48E.1 also locks typed API 0.4 step results, count-only score sinks,
 reusable SoA audit buffers, separate command/lifecycle/fill reports, compact
-validated Rust order state, and reset/compaction parity. `auto` remains Python;
-the native extra remains empty until the CPython 3.11/3.12/3.13 manylinux
-clean-install workflow passes.
+validated Rust order state, and reset/lifecycle parity. This paragraph records
+the historical pre-promotion state; the current Stage-B local policy is the
+bounded static/IR/batch policy above. The native extra remains empty until the
+CPython 3.11/3.12/3.13 manylinux clean-install workflow passes.
 
 Ecosystem positioning:
 
@@ -639,15 +745,19 @@ fills, positions, account state, and performance report.
 Install the released core package:
 
 ```bash
-pip install quantbt-engine==1.0.7
+pip install --upgrade quantbt-engine
 ```
 
-Optional reports and third-party validation:
+Optional optimization, reports, and third-party validation:
 
 ```bash
-pip install "quantbt-engine[reports,validation]==1.0.7"
+pip install --upgrade "quantbt-engine[optimization,reports,validation]"
 ```
 
+Walk-forward parameter search specifically requires the `optimization` extra.
+Read the [causal WFO guide](docs/walkforward_causal.md) before reporting OOS
+metrics from a fold-local schedule.
+
 Development from this repository:
 
 ```bash
@@ -671,8 +781,8 @@ feature is under development:
 pip install -e /root/bobby/pool_alpha/quantbt
 ```
 
-After the release is approved, downstream services should use
-`pip install quantbt-engine==1.0.7` and keep the unchanged import
+For reproducible deployments, pin a published version such as
+`pip install quantbt-engine==1.0.9` and keep the unchanged import
 `from quantbt import QuantBTEndpoint`.
 
 ## Quick Start
@@ -803,6 +913,31 @@ result = wf.backtest(data=df, param_ranges=param_ranges)
 wf.show_metrics(scope="auto")
 ```
 
+Multi-fold WFO keeps `optimization_schedule="global"` as the compatible
+default. Phase 49A also exposes two explicit fold-local schedules:
+
+- `mode_1_decay + per_fold_decay`: one study per fold, with same-fold OOS used
+  for final decay candidate selection (`selection_adjusted_oos`);
+- `mode_4_is_only_robust + per_fold_causal`: one study per fold, with strict
+  IS-only selection before outer OOS execution.
+- `mode_1_decay + per_fold_causal`: one outer study per fold, where Mode 1
+  decay is measured only on explicit nested inner folds contained in that
+  outer IS window; outer OOS remains untouched until parameters are frozen.
+
+Both schedules stitch one continuous target tape and run accounting once with
+`fold_boundary_position_policy="carry"`. See the [causal WFO guide]
+(docs/walkforward_causal.md), [docs/endpoint.md](docs/endpoint.md), and
+[methodology/walk_forward.md](methodology/walk_forward.md) for selection claims,
+strictness boundaries, and audit metadata.
+
+Phase 49B keeps this API stable. Endpoint-backed optimization prepares market
+and fold state once and uses scalar-only trial reports by default. Audit the
+lifecycle through `prepared_wfo_context`, `prepared_scoring_cache`,
+`trial_ledger_mode`, and `performance_profile` in walk-forward metadata.
+Nested Mode 1 also records `inner_validation`, `inner_fold_table`, and
+`chronological_validation_claim` so services can distinguish retrospective,
+selection-adjusted, and strict outer-OOS results.
+
 `scope="auto"` reports only the tested/OOS segment for walk-forward and
 train/test runs. Pass `scope="full"` when you need to audit the full stitched
 timeline.
@@ -852,7 +987,13 @@ backend, endpoint, or strategy route to use.
 | Market/limit/stop fill behavior | [Order fill policies](docs/order_fill_policies.md) |
 | Nautilus validation and report bundles | [Nautilus backend](docs/nautilus_backend.md) |
 | Pair, basket, hedge-ratio package behavior | [Pair and basket guide](docs/pair_basket_guide.md) |
+| Causal WFO schedules, outer-OOS claims, and audit metadata | [Causal WFO guide](docs/walkforward_causal.md) |
 | Walk-forward methodology and anti-leakage scoring | [Walk-forward methodology](docs/walkforward_methodology_vi.md) |
+| Opt-in Rust strategy templates, batch scoring, and causal OOS batch folds | [Native strategy IR and batch](docs/native_strategy_ir.md) |
+| Python/Rust plan ownership and backend routing | [Execution-plan architecture](docs/architecture/execution-plan.md) |
+| Exact staged core/native pair and maturity matrix | [Generated native compatibility](docs/contracts/generated_product_compatibility.md) |
+| Build, clean-install, and verify local native wheels | [Native companion installation](docs/native/install.md) |
+| Workload-scoped benchmark methodology | [Benchmarking governance](docs/performance/benchmarking.md) |
 | Runnable smoke templates | [Examples index](examples/README.md) |
 
 Key examples:

{quantbt_engine-1.0.7 → quantbt_engine-1.0.9}/README.md

@@ -1,6 +1,7 @@
 # QuantBT
 
 ![Python](https://img.shields.io/badge/python-3.11%2B-blue)
+[![PyPI](https://img.shields.io/pypi/v/quantbt-engine.svg?label=PyPI)](https://pypi.org/project/quantbt-engine/)
 ![Numba](https://img.shields.io/badge/core-numba-00A86B)
 ![Backtesting](https://img.shields.io/badge/backtesting-vectorized%20%7C%20event--driven-black)
 ![Nautilus](https://img.shields.io/badge/nautilus-optional-6f42c1)
@@ -18,6 +19,10 @@ The goal is simple: make alpha research fast enough for iteration, strict
 enough for institutional-style review, and readable enough that stakeholders can
 audit how a result was produced.
 
+QuantBT is published on [PyPI as `quantbt-engine`](https://pypi.org/project/quantbt-engine/).
+Install the current public release with `pip install --upgrade quantbt-engine`;
+the import remains `from quantbt import QuantBTEndpoint`.
+
 Current portfolio status: `native_portfolio` is the default multi-symbol
 backend. It supports long/short, market-neutral, directional, equal-weight,
 risk-parity, and beta-neutral portfolio modes, with live-equity sizing and
@@ -29,7 +34,7 @@ historical reproduction.
 - One public API for notebooks, services, portfolio research, and validation.
 - Native vectorized engines for fast sweeps and large parameter grids.
 - Native event-driven engines for market/limit orders, fills, baskets, and
-  arbitrage package execution.
+  package execution, with Rust auto-promotion limited to certified workloads.
 - Prepared service contexts for repeated signal/portfolio replays on the same
   market tape without re-normalizing pandas data each run.
 - Native portfolio engine with target weights, target notionals, target units,
@@ -65,6 +70,7 @@ bt = QuantBTEndpoint.event_driven(
     input_mode="strategy",   # strategy | orders
     profile="research",      # research | optimize | audit
     backend="auto",          # auto | python | rust
+    execution_contract="event_lifecycle_v3_next_open",
     initial_capital=20_000,
     leverage=5,
     fee_rate=0.0005,          # one-way fee per fill
@@ -83,6 +89,21 @@ event artifacts. For an upstream order planner, switch to
 backend follows the release policy; `rust` is an explicit request for the
 optional capability-gated native wheel.
 
+An arbitrary `strategy=...` callback remains a Python-authoritative route,
+including when `backend="auto"` and a local native wheel is installed. The
+current automatic Rust routes are a pre-built static V2/V3 command tape with
+at least 10,000 bars, or a bounded `NativeStrategyIR` request with at least
+2,000 bars. Inspect `result.metadata["native_event_promotion_v1"]` to see the
+resolved backend, threshold, policy rule, and fallback reason for every run.
+
+The compatibility default is the frozen
+`event_lifecycle_v2_next_bar_close` behavior. Select
+`event_lifecycle_v3_next_open` for real next-open market fills, favorable
+limit-gap improvement, adverse stop-gap execution, and conservative flagged
+stop-limit ambiguity. V3 requires an `open` column and is parity-tested across
+the Python and Rust backends. The machine-readable registry and audit fields
+are documented in [Native Event Contract Registry](docs/contracts/contract_registry.md).
+
 The strategy owns signal generation and look-ahead control. QuantBT owns the
 causal order lifecycle and accounting. Advanced users can still call
 `native_event_strategy(...)` or `native_event_lifecycle(...)` directly when a
@@ -168,6 +189,21 @@ tape. Normal `.backtest(...)` remains defensive and backward-compatible.
 Cython/C++ remains deferred because the larger benchmark still points to
 facade/report overhead rather than pure Numba kernels.
 
+Latest Phase 49B WFO benchmark (1,000 daily bars, identical seeds, folds,
+trials, strategies, account settings, and accounting kernels):
+
+| WFO workload | Phase 49A reference | Phase 49B prepared/scalar | Speedup | Parity |
+|---|---:|---:|---:|---|
+| Portfolio global, 1 study x 16 trials | 0.386s | 0.330s | 1.17x | exact |
+| Single-symbol causal, 6 studies x 16 trials | 4.051s | 1.781s | 2.27x | exact |
+
+Phase 49B prepares aligned WFO fold state once, scores trials directly from
+accounting arrays, and compacts completed Optuna ledgers. It does not cache user
+strategy signals or alter objectives. The isolated warm peak-RSS difference was
+within +/-0.15%, so the result is reported as an RSS plateau rather than a memory
+reduction. Reproduce it with
+`python benchmarks/run_phase49b_wfo_performance.py --rows 1000 --trials 16`.
+
 Latest Phase 31 intrabar execution benchmark:
 
 | Route | Workload | Runtime | Throughput | Ratio | Parity |
@@ -205,7 +241,70 @@ selection semantics inside `walkforward.py`. Read
 `benchmarks/results/optimization_overhead.md` for signal, intrabar, portfolio,
 arbitrage/grid/options fallback examples and benchmark details.
 
-### Phase 46F package and dual-backend release evidence
+### Current governed Rust routes and benchmark evidence
+
+Rust is execution-authoritative only where the public request, accounting
+contract, installed-wheel parity corpus, and promotion policy have all been
+certified. The generated Stage-B policy has this deliberately narrow scope:
+
+| Route | Rust behavior with a matching local companion | Public default elsewhere |
+|---|---|---|
+| Static V2/V3 `OrderCommand` tape | `auto` at 10,000+ bars | Python |
+| Bounded Native Strategy IR, batch, causal-fold scorer | `auto` at 2,000+ bars | Python |
+| `run_portfolio_target_market(...)` | explicit Rust helper | no generic endpoint promotion |
+| `run_atomic_package_market(...)` | explicit Rust helper | no generic endpoint promotion |
+| Python callback/reactive, generic portfolio/basket/arbitrage/options | not promoted | Python |
+
+The bounded Rust strategy IR covers precomputed signal targets, structural
+Grid levels, periodic DCA, and fixed bracket/OCO transitions. Python callbacks,
+reactive strategies, and generic portfolio/package/arbitrage execution remain
+Python compatibility routes by design.
+
+Phase 54B.3 also certifies two intentionally explicit Rust helpers,
+`run_portfolio_target_market(...)` and `run_atomic_package_market(...)`, for
+linear quote-settled gross-cross `target_units` and one ordered same-bar
+all-or-none market package respectively. They do not change generic endpoint
+routing or claim venue-native multi-leg execution; the bounded contract,
+parity corpus, and benchmark evidence are documented in
+[`docs/native_event_rust_full_contract.md`](docs/native_event_rust_full_contract.md).
+On the governed 2,000-bar x 8-symbol fixture, their Rust score paths measured
+3.594 ms (556,551 bars/s) for target units and 3.512 ms (569,514 bars/s) for
+the atomic package, versus Python event-oracle score paths of 33.493 ms and
+19.735 ms respectively. These are bounded direct-route measurements; audit
+report adaptation is intentionally timed and reported separately.
+
+The local five-repeat public-route evidence below passed exact Python/Rust
+canonical-trace and accounting parity before timing. It is deliberately not a
+universal Rust speed claim: static public facade time is dominated by common
+Python preparation/report adaptation, while typed IR score and shared batch
+avoid those per-scenario costs.
+
+| Workload | Bars | Rust median | Rust throughput | Python median | Python throughput |
+|---|---:|---:|---:|---:|---:|
+| Static public compact | 10,000 | 63.612 ms | 157,203 bars/s | 53.606 ms | 186,545 bars/s |
+| Static public audit | 10,000 | 6.024 s | 1,660 bars/s | 5.924 s | 1,688 bars/s |
+| Native IR score | 2,000 | 0.741 ms | 2.70M bars/s | 31.565 ms | 63,361 bars/s |
+| Native IR batch, 64 scenarios | 128,000 | 11.379 ms | 11.25M bars/s | - | - |
+| Native IR causal fold, 64 scenarios | 64,000 | 7.386 ms | 8.67M bars/s | - | - |
+
+The Rust IR score has one boundary call, zero Python callbacks, and no audit
+replay. Batch/fold execution has one boundary call and zero prepared-market
+copies per scenario; its repeated-run RSS delta was 8-16 KiB on this host. An
+audit result is intentionally a cold reporting path: its typed Rust output is
+adapted to the normal `BacktestResultV2` without rerunning execution. Full
+evidence is in
+[`phase54b2/public_routes.md`](benchmarks/native_event/results/phase54b2/public_routes.md)
+and the support boundary is in
+[`docs/native_strategy_ir.md`](docs/native_strategy_ir.md).
+
+Phase 54B.4 adds an installed-wheel release gate, rather than a new speed
+claim. It proves clean core-only fallback, exact core/native-pair handshake,
+promotion decisions, and Python/Rust accounting parity for every governed
+route. The public `quantbt-engine` wheel remains core-only until a separately
+approved native wheel release; see the
+[native release handoff](docs/migration/native_release_handoff.md).
+
+### Historical Phase 46F package and dual-backend release evidence
 
 The core distribution is packaged as `quantbt-engine` and imports as
 `quantbt`. Its release gate is independent from the optional experimental Rust
@@ -213,8 +312,8 @@ wheel:
 
 | Release artifact | Current status | Backend policy |
 |---|---|---|
-| `quantbt-engine==1.0.7` wheel/sdist | release-ready after local/TestPyPI approval | Python canonical; all existing endpoints remain available |
-| `quantbt-native` PyO3 wheel | experimental, not published | explicit `native_backend="rust"` only |
+| `quantbt-engine` wheel/sdist | published on PyPI | Python canonical; all existing endpoints remain available |
+| `quantbt-native` PyO3 wheel | staged, not published | local Stage-B `auto` only for certified static/IR/batch rows |
 | `quantbt-engine[native]` | intentionally empty | no dependency is advertised before native certification |
 
 The committed Phase 46F rerun compares the same prepared static tape and keeps
@@ -280,7 +379,7 @@ Raw Phase 47D artifacts are kept under
 
 ### Phase 48F final release handoff
 
-The core `quantbt-engine` 1.0.7 artifact gate is now implemented locally and
+The core `quantbt-engine` 1.0.8 artifact gate is now implemented locally and
 in the release workflows: exact version/ref validation, wheel and sdist
 `twine check`, archive allowlist and secret scan, clean import plus `pip check`,
 and a SHA256 release manifest. The TestPyPI workflow is manual and OIDC
@@ -322,7 +421,10 @@ The release workflow is documented in
 [`docs/release_packaging.md`](docs/release_packaging.md): build and inspect
 wheel/sdist, run clean-install and `pip check`, publish an RC to TestPyPI with
 OIDC, then publish the final core package through the protected PyPI
-environment. The exact handoff fields and artifact-hash procedure are in
+environment. The native companion scope, rollback controls, and installed-wheel
+certification handoff are in
+[`docs/migration/native_release_handoff.md`](docs/migration/native_release_handoff.md).
+The exact handoff fields and artifact-hash procedure are in
 [`docs/testpypi_release_checklist.md`](docs/testpypi_release_checklist.md).
 No long-lived token is required. Native optimization remains an
 open, domain-preserving roadmap for portfolio, arbitrage, options, vectorized,
@@ -390,8 +492,10 @@ Phase 48E also reduced the static explicit Rust score to `0.000302s`
 scalar Rust output contract and prepared command-tape reuse, so they are
 reported separately from callback execution. Rust and Python fingerprints,
 fees, positions, fills, events, rejection counters, and final equity passed.
-`backend="auto"` remains Python and `[native]` remains empty until the public
-`quantbt-native` wheel matrix is clean-install certified.
+At Phase 48E this historical benchmark had `auto` pinned to Python. The later
+Phase 54B.2 local Stage-B policy promotes only the certified static/IR/batch
+rows documented above; `[native]` remains empty until a public native-wheel
+matrix is clean-install certified.
 
 ### Phase 48E.1 native production-closure evidence
 
@@ -422,9 +526,10 @@ facade; it is not a universal Rust speed claim.
 
 Phase 48E.1 also locks typed API 0.4 step results, count-only score sinks,
 reusable SoA audit buffers, separate command/lifecycle/fill reports, compact
-validated Rust order state, and reset/compaction parity. `auto` remains Python;
-the native extra remains empty until the CPython 3.11/3.12/3.13 manylinux
-clean-install workflow passes.
+validated Rust order state, and reset/lifecycle parity. This paragraph records
+the historical pre-promotion state; the current Stage-B local policy is the
+bounded static/IR/batch policy above. The native extra remains empty until the
+CPython 3.11/3.12/3.13 manylinux clean-install workflow passes.
 
 Ecosystem positioning:
 
@@ -589,15 +694,19 @@ fills, positions, account state, and performance report.
 Install the released core package:
 
 ```bash
-pip install quantbt-engine==1.0.7
+pip install --upgrade quantbt-engine
 ```
 
-Optional reports and third-party validation:
+Optional optimization, reports, and third-party validation:
 
 ```bash
-pip install "quantbt-engine[reports,validation]==1.0.7"
+pip install --upgrade "quantbt-engine[optimization,reports,validation]"
 ```
 
+Walk-forward parameter search specifically requires the `optimization` extra.
+Read the [causal WFO guide](docs/walkforward_causal.md) before reporting OOS
+metrics from a fold-local schedule.
+
 Development from this repository:
 
 ```bash
@@ -621,8 +730,8 @@ feature is under development:
 pip install -e /root/bobby/pool_alpha/quantbt
 ```
 
-After the release is approved, downstream services should use
-`pip install quantbt-engine==1.0.7` and keep the unchanged import
+For reproducible deployments, pin a published version such as
+`pip install quantbt-engine==1.0.9` and keep the unchanged import
 `from quantbt import QuantBTEndpoint`.
 
 ## Quick Start
@@ -753,6 +862,31 @@ result = wf.backtest(data=df, param_ranges=param_ranges)
 wf.show_metrics(scope="auto")
 ```
 
+Multi-fold WFO keeps `optimization_schedule="global"` as the compatible
+default. Phase 49A also exposes two explicit fold-local schedules:
+
+- `mode_1_decay + per_fold_decay`: one study per fold, with same-fold OOS used
+  for final decay candidate selection (`selection_adjusted_oos`);
+- `mode_4_is_only_robust + per_fold_causal`: one study per fold, with strict
+  IS-only selection before outer OOS execution.
+- `mode_1_decay + per_fold_causal`: one outer study per fold, where Mode 1
+  decay is measured only on explicit nested inner folds contained in that
+  outer IS window; outer OOS remains untouched until parameters are frozen.
+
+Both schedules stitch one continuous target tape and run accounting once with
+`fold_boundary_position_policy="carry"`. See the [causal WFO guide]
+(docs/walkforward_causal.md), [docs/endpoint.md](docs/endpoint.md), and
+[methodology/walk_forward.md](methodology/walk_forward.md) for selection claims,
+strictness boundaries, and audit metadata.
+
+Phase 49B keeps this API stable. Endpoint-backed optimization prepares market
+and fold state once and uses scalar-only trial reports by default. Audit the
+lifecycle through `prepared_wfo_context`, `prepared_scoring_cache`,
+`trial_ledger_mode`, and `performance_profile` in walk-forward metadata.
+Nested Mode 1 also records `inner_validation`, `inner_fold_table`, and
+`chronological_validation_claim` so services can distinguish retrospective,
+selection-adjusted, and strict outer-OOS results.
+
 `scope="auto"` reports only the tested/OOS segment for walk-forward and
 train/test runs. Pass `scope="full"` when you need to audit the full stitched
 timeline.
@@ -802,7 +936,13 @@ backend, endpoint, or strategy route to use.
 | Market/limit/stop fill behavior | [Order fill policies](docs/order_fill_policies.md) |
 | Nautilus validation and report bundles | [Nautilus backend](docs/nautilus_backend.md) |
 | Pair, basket, hedge-ratio package behavior | [Pair and basket guide](docs/pair_basket_guide.md) |
+| Causal WFO schedules, outer-OOS claims, and audit metadata | [Causal WFO guide](docs/walkforward_causal.md) |
 | Walk-forward methodology and anti-leakage scoring | [Walk-forward methodology](docs/walkforward_methodology_vi.md) |
+| Opt-in Rust strategy templates, batch scoring, and causal OOS batch folds | [Native strategy IR and batch](docs/native_strategy_ir.md) |
+| Python/Rust plan ownership and backend routing | [Execution-plan architecture](docs/architecture/execution-plan.md) |
+| Exact staged core/native pair and maturity matrix | [Generated native compatibility](docs/contracts/generated_product_compatibility.md) |
+| Build, clean-install, and verify local native wheels | [Native companion installation](docs/native/install.md) |
+| Workload-scoped benchmark methodology | [Benchmarking governance](docs/performance/benchmarking.md) |
 | Runnable smoke templates | [Examples index](examples/README.md) |
 
 Key examples:

{quantbt_engine-1.0.7 → quantbt_engine-1.0.9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "quantbt-engine"
-version = "1.0.7"
+version = "1.0.9"
 description = "Transparent, high-performance quantitative backtesting engine"
 readme = "README.md"
 requires-python = ">=3.11,<3.14"
@@ -70,6 +70,7 @@ all = [
 
 [project.urls]
 Homepage = "https://github.com/BobbyAxerol/quantbt"
+PyPI = "https://pypi.org/project/quantbt-engine/"
 Repository = "https://github.com/BobbyAxerol/quantbt"
 Issues = "https://github.com/BobbyAxerol/quantbt/issues"
 Documentation = "https://github.com/BobbyAxerol/quantbt/tree/main/docs"