backtest-doctor 0.4.0rc4__tar.gz

backtest_doctor-0.4.0rc4/CONTRIBUTING.md

@@ -0,0 +1,9 @@
+# Contributing
+
+1. Discuss changes in an issue or pull request and keep each contribution focused on a reproducible validation rule.
+2. Include a minimal **synthetic** test fixture. Do not share account, market-vendor, proprietary strategy, portfolio, PnL, or private trading data.
+3. Keep the runtime standard-library-only, fully offline, deterministic, compatible with Python 3.10+, and free from dynamic code execution.
+4. Document false-positive conditions and what a result **does not** establish.
+5. Run `PYTHONPATH=src python -m unittest discover -s tests -v` before submitting. CI covers Linux, Windows and macOS after publication.
+
+No trading signals, execution accounts, proprietary parameters, real order histories or exchange data belong in this repository.

backtest_doctor-0.4.0rc4/LICENSE

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

backtest_doctor-0.4.0rc4/MANIFEST.in

@@ -0,0 +1,7 @@
+include LICENSE README.md SECURITY.md CONTRIBUTING.md
+recursive-include examples *.csv *.json
+recursive-include docs *.md
+recursive-include tests *.py
+prune demo
+prune .git
+recursive-include tools *.py

backtest_doctor-0.4.0rc4/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: backtest-doctor
+Version: 0.4.0rc4
+Summary: Offline backtest integrity checks for OHLCV, trade timing, and stability
+Author: suguobin2021
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Backtest Doctor
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-blue.svg)](pyproject.toml)
+
+**An offline, zero-runtime-dependency integrity check for exported backtests.** Validate timestamped OHLCV data, declared signal-to-fill timing, and how aggregate trade returns change under transaction costs. Produce deterministic, minimal JSON and self-contained HTML reports without including raw trades or filenames.
+
+> This tool checks the evidence you supply. It does **not** inspect or execute strategy source code; it cannot prove a strategy is free of look-ahead bias, overfitting, survivorship bias, or execution risk. `PASS` means only that the implemented checks found no violations in the supplied fields.
+
+## Install
+
+Requires Python 3.10+. After the package is published to PyPI:
+
+```sh
+python -m pip install backtest-doctor
+```
+
+Until PyPI publication, install the wheel from a verified release artifact or install this repository from source:
+
+```sh
+python -m pip install .
+python -m backtest_doctor --help
+```
+
+## 30-second synthetic demo
+
+```sh
+# Run from the repository root; ALL sample files are synthetic.
+python -m backtest_doctor bundle \
+  --ohlcv-file examples/ohlcv_good.csv \
+  --ledger-file examples/ledger_bad.csv \
+  --stability-file examples/stability_demo.csv \
+  --html doctor-report.html --fail-on-warn
+```
+
+The intentionally bad ledger produces `FAIL` and exits **1**; this is expected, not an installation failure. Try `examples/ledger_good.csv` instead to see a clean causal timing check. Stability may still return `WARN` for small samples. The command exits `0` for PASS, `1` for FAIL (and WARN with `--fail-on-warn`), and `2` for rejected input. For an HTML report opened locally, use a **new filename**; the CLI will not overwrite an existing file.
+
+For a **complete cross-platform, beginner-friendly walkthrough**, follow [the synthetic quickstart](docs/QUICKSTART.md). For the manual, secretless PyPI publishing process, see [the distribution guide](docs/PYPI_PUBLISHING.md).
+
+For CI integration in other repositories, see the [experimental GitHub Action](docs/ACTION_USAGE.md).
+
+Add `--explain` to any audit command for **fixed, data-free diagnostic explanations and investigation suggestions**. Explanations are opt-in, preserving the default JSON format. See the [finding guide](docs/FINDING_CODES.md).
+
+**NEW: experimental framework-export CSV adapters:** inspect settled trade summaries from `backtesting.py`, `vectorbt`, or a manually prepared Freqtrade CSV subset (not native Freqtrade ZIP/JSON):
+
+```sh
+python -m backtest_doctor import-trades examples/backtesting_py_synthetic.csv --framework backtesting-py
+python -m backtest_doctor import-trades examples/vectorbt_synthetic.csv --framework vectorbt
+python -m backtest_doctor import-trades examples/freqtrade_csv_synthetic.csv --framework freqtrade-csv
+```
+
+These checks cannot verify causal signal timing, and they do not double-count framework-reported costs by default. See [framework CSV contracts, known limits and privacy model](docs/FRAMEWORK_TRADES.md).
+
+For synthetic examples of alternate CSV column names (without copying any private exports), see [declarative column mapping](docs/COLUMN_MAPPING.md).
+
+## Checks
+
+| Mode | Input | Detects / summarizes |
+| --- | --- | --- |
+| `ohlcv` | CSV with `timestamp,open,high,low,close,volume` | Invalid candle geometry, duplicate/non-monotone timestamps, irregular cadence (when configured) |
+| `ledger` | CSV with `signal_bar_close,entry_time,next_bar_open` | Entry before or at signal close; entry before claimed next bar; both stop and target hit within the same bar |
+| `stability` | CSV with `exit_time,gross_return` | Trade count, time-coverage warnings, cost-scenario expectancy, PF, win rate, simplified sequential equity/drawdown proxies |
+| `bundle` | All three CSVs | All checks, one aggregate report and exit status |
+
+Single-mode invocation:
+
+```sh
+python -m backtest_doctor ohlcv examples/ohlcv_good.csv --interval-seconds 60
+python -m backtest_doctor ledger examples/ledger_bad.csv
+python -m backtest_doctor stability examples/stability_demo.csv
+```
+
+**Profit factor is undefined (reported as `null`) if no negative trades exist.** All stability returns are fractions: `0.01` means 1%. Compounded returns and drawdown are explicitly **proxies**, not portfolio NAV or account-level PnL. Overlapping trades, leverage, funding, slippage, execution limits and corporate actions are not reconstructed. Costs are specified in basis points per trade (default 0, 8, 20 bps).
+
+## Privacy model
+
+No networking, telemetry, trade execution, or strategy source evaluation. Reads local regular CSV files only (up to 10 MiB, 100,000 rows) and emits aggregate metrics and coded findings only. It is intentionally **not a security sandbox**: do not use it to evaluate untrusted adversarial filesystem access, and inspect reports before sharing. See [SECURITY.md](SECURITY.md).
+
+This repo uses synthetic fixtures only. It has no live trading records, private quantitative research databases, exchange API keys, real account IDs, strategy-specific parameters, server credentials, or licensed market datasets. Only explicitly allowlisted code, docs, tests, and synthetic fixtures are bundled by the build process.
+
+## Contribute and reproducibility
+
+```sh
+python -m unittest discover -s tests -v
+python -m pip wheel . --no-deps -w dist
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md), [docs/LIMITATIONS.md](docs/LIMITATIONS.md), and [docs/RELEASE_CHECKLIST.md](docs/RELEASE_CHECKLIST.md). MIT-licensed. No claim of investment performance or financial advice.

backtest_doctor-0.4.0rc4/README.md

@@ -0,0 +1,88 @@
+# Backtest Doctor
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-blue.svg)](pyproject.toml)
+
+**An offline, zero-runtime-dependency integrity check for exported backtests.** Validate timestamped OHLCV data, declared signal-to-fill timing, and how aggregate trade returns change under transaction costs. Produce deterministic, minimal JSON and self-contained HTML reports without including raw trades or filenames.
+
+> This tool checks the evidence you supply. It does **not** inspect or execute strategy source code; it cannot prove a strategy is free of look-ahead bias, overfitting, survivorship bias, or execution risk. `PASS` means only that the implemented checks found no violations in the supplied fields.
+
+## Install
+
+Requires Python 3.10+. After the package is published to PyPI:
+
+```sh
+python -m pip install backtest-doctor
+```
+
+Until PyPI publication, install the wheel from a verified release artifact or install this repository from source:
+
+```sh
+python -m pip install .
+python -m backtest_doctor --help
+```
+
+## 30-second synthetic demo
+
+```sh
+# Run from the repository root; ALL sample files are synthetic.
+python -m backtest_doctor bundle \
+  --ohlcv-file examples/ohlcv_good.csv \
+  --ledger-file examples/ledger_bad.csv \
+  --stability-file examples/stability_demo.csv \
+  --html doctor-report.html --fail-on-warn
+```
+
+The intentionally bad ledger produces `FAIL` and exits **1**; this is expected, not an installation failure. Try `examples/ledger_good.csv` instead to see a clean causal timing check. Stability may still return `WARN` for small samples. The command exits `0` for PASS, `1` for FAIL (and WARN with `--fail-on-warn`), and `2` for rejected input. For an HTML report opened locally, use a **new filename**; the CLI will not overwrite an existing file.
+
+For a **complete cross-platform, beginner-friendly walkthrough**, follow [the synthetic quickstart](docs/QUICKSTART.md). For the manual, secretless PyPI publishing process, see [the distribution guide](docs/PYPI_PUBLISHING.md).
+
+For CI integration in other repositories, see the [experimental GitHub Action](docs/ACTION_USAGE.md).
+
+Add `--explain` to any audit command for **fixed, data-free diagnostic explanations and investigation suggestions**. Explanations are opt-in, preserving the default JSON format. See the [finding guide](docs/FINDING_CODES.md).
+
+**NEW: experimental framework-export CSV adapters:** inspect settled trade summaries from `backtesting.py`, `vectorbt`, or a manually prepared Freqtrade CSV subset (not native Freqtrade ZIP/JSON):
+
+```sh
+python -m backtest_doctor import-trades examples/backtesting_py_synthetic.csv --framework backtesting-py
+python -m backtest_doctor import-trades examples/vectorbt_synthetic.csv --framework vectorbt
+python -m backtest_doctor import-trades examples/freqtrade_csv_synthetic.csv --framework freqtrade-csv
+```
+
+These checks cannot verify causal signal timing, and they do not double-count framework-reported costs by default. See [framework CSV contracts, known limits and privacy model](docs/FRAMEWORK_TRADES.md).
+
+For synthetic examples of alternate CSV column names (without copying any private exports), see [declarative column mapping](docs/COLUMN_MAPPING.md).
+
+## Checks
+
+| Mode | Input | Detects / summarizes |
+| --- | --- | --- |
+| `ohlcv` | CSV with `timestamp,open,high,low,close,volume` | Invalid candle geometry, duplicate/non-monotone timestamps, irregular cadence (when configured) |
+| `ledger` | CSV with `signal_bar_close,entry_time,next_bar_open` | Entry before or at signal close; entry before claimed next bar; both stop and target hit within the same bar |
+| `stability` | CSV with `exit_time,gross_return` | Trade count, time-coverage warnings, cost-scenario expectancy, PF, win rate, simplified sequential equity/drawdown proxies |
+| `bundle` | All three CSVs | All checks, one aggregate report and exit status |
+
+Single-mode invocation:
+
+```sh
+python -m backtest_doctor ohlcv examples/ohlcv_good.csv --interval-seconds 60
+python -m backtest_doctor ledger examples/ledger_bad.csv
+python -m backtest_doctor stability examples/stability_demo.csv
+```
+
+**Profit factor is undefined (reported as `null`) if no negative trades exist.** All stability returns are fractions: `0.01` means 1%. Compounded returns and drawdown are explicitly **proxies**, not portfolio NAV or account-level PnL. Overlapping trades, leverage, funding, slippage, execution limits and corporate actions are not reconstructed. Costs are specified in basis points per trade (default 0, 8, 20 bps).
+
+## Privacy model
+
+No networking, telemetry, trade execution, or strategy source evaluation. Reads local regular CSV files only (up to 10 MiB, 100,000 rows) and emits aggregate metrics and coded findings only. It is intentionally **not a security sandbox**: do not use it to evaluate untrusted adversarial filesystem access, and inspect reports before sharing. See [SECURITY.md](SECURITY.md).
+
+This repo uses synthetic fixtures only. It has no live trading records, private quantitative research databases, exchange API keys, real account IDs, strategy-specific parameters, server credentials, or licensed market datasets. Only explicitly allowlisted code, docs, tests, and synthetic fixtures are bundled by the build process.
+
+## Contribute and reproducibility
+
+```sh
+python -m unittest discover -s tests -v
+python -m pip wheel . --no-deps -w dist
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md), [docs/LIMITATIONS.md](docs/LIMITATIONS.md), and [docs/RELEASE_CHECKLIST.md](docs/RELEASE_CHECKLIST.md). MIT-licensed. No claim of investment performance or financial advice.

backtest_doctor-0.4.0rc4/SECURITY.md

@@ -0,0 +1,7 @@
+# Security and disclosure
+
+Do not submit any real trading account records, private trading data, private strategy code, exchange credentials, production logs, SSH keys, or licensed datasets in a public issue or PR. Use the synthetic fixtures in `examples/` to reproduce failures.
+
+The application processes local CSV files and generates aggregate reports; it does not call network endpoints, transmit telemetry, connect to a brokerage, or execute strategy files. It is not a general-purpose sandbox for hostile file input or malicious filesystem races. It has explicit file limits and minimizes the output surface but does not guarantee anonymity.
+
+When reporting a security issue, use GitHub's private vulnerability reporting (if enabled), or contact the repository owner through an established private channel. Do not post exploit material or credentials in public issues.

backtest_doctor-0.4.0rc4/docs/ACTION_USAGE.md

@@ -0,0 +1,54 @@
+# GitHub Actions integration (experimental)
+
+Use the composite action in another public repository, **with synthetic test
+fixtures first**. A consumer workflow example (after checking out your own
+repo) is:
+
+```yaml
+name: Audit example backtest exports
+on: [pull_request]
+permissions:
+  contents: read
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - uses: suguobin2021/backtest-doctor/.github/actions/audit@main
+        with:
+          ohlcv-file: examples/ohlcv_good.csv
+          ledger-file: examples/ledger_good.csv
+          stability-file: examples/stability_demo.csv
+          fail-on-warn: 'false'
+          explain: 'true'
+```
+
+Replace the example paths with CSV files that match the documented schemas.
+The sample has **four synthetic trades** and returns WARN (low trade count),
+which exits 0 unless `fail-on-warn: 'true'` is selected. A genuinely invalid
+ledger returns FAIL and exits 1. The caller must check its own datasets and
+permissions, since no private datasets are bundled.
+
+**Versioning:** `@main` is suitable only for initial testing. For reproducible
+production CI, pin the action to an audited full commit SHA from the main
+branch that includes `.github/actions/audit/action.yml`. The older
+`v0.4.0rc1` tag predates the action and must not be used for this feature.
+
+**Privacy:** execution occurs on GitHub-hosted runners, NOT the user's private
+machine. GitHub Actions may retain console output; JSON reports contain
+aggregate statistics and row numbers. Do not run this on sensitive private
+trade files unless your own data-handling policy permits processing on that
+runner. The CLI itself does not transmit trade records or API requests, but
+its packaging dependencies can be downloaded during installation.
+
+Set `explain: 'true'` to include fixed, data-free descriptions and next steps in aggregate results. These suggestions do not validate strategy profitability. See [finding codes](FINDING_CODES.md).
+
+**Limits:** the action checks exported CSV fields, not trading strategies or
+alpha source code. A PASS is not proof of causality or future profitability.
+
+## Optional mapped CSV columns
+
+Supply columns-file: examples/columns_synthetic.json to map alternate CSV headings.
+See the column mapping guide; never send private trading data to hosted CI without authorization.

backtest_doctor-0.4.0rc4/docs/COLUMN_MAPPING.md

@@ -0,0 +1,41 @@
+# Portable CSV column aliases (experimental)
+
+Backtest Doctor reads local, regular CSV files. To audit a file that uses a different
+set of column headings, pass a **declarative JSON mapping**. This only renames
+field labels for the documented checks. It does **not** integrate with a
+backtesting framework, execute a strategy, infer trade semantics, or correct an
+incorrect timestamp or return convention.
+
+```sh
+python -m backtest_doctor bundle \
+  --ohlcv-file examples/ohlcv_alias.csv \
+  --ledger-file examples/ledger_alias.csv \
+  --stability-file examples/stability_alias.csv \
+  --columns examples/columns_synthetic.json
+```
+
+The result is WARN due to the deliberately small synthetic sample, with exit
+code 0 unless --fail-on-warn is passed. The example is made-up data and has no
+connection to a live strategy, broker, exchange, or account.
+
+```json
+{
+  "ohlcv": {"timestamp": "Date", "open": "Open", "high": "High", "low": "Low", "close": "Close", "volume": "Volume"},
+  "ledger": {"signal_bar_close": "SignalClose", "entry_time": "Entered", "next_bar_open": "NextOpen"},
+  "stability": {"exit_time": "Exited", "gross_return": "GrossReturn"}
+}
+```
+
+Each left-hand key is a canonical Backtest Doctor column and the value is the
+exact source CSV column. All unspecified canonical fields must already
+use canonical names. Unknown names, duplicates, collisions, missing mapped
+columns, oversized or symlinked JSON inputs are rejected.
+
+**This is not a vendor adapter.** Some frameworks use percentage points
+(1.5 means 1.5%) while Backtest Doctor expects fractions (0.015 means 1.5%).
+Column mapping cannot correct semantic errors; check them separately.
+
+Privacy: the local CLI reports aggregate diagnostic data but does not echo
+raw inputs, source column labels or paths. GitHub-hosted Actions run on GitHub
+infrastructure; do not use hosted CI for private trading data without a
+separate data-handling approval.

backtest_doctor-0.4.0rc4/docs/FINDING_CODES.md

@@ -0,0 +1,31 @@
+# Finding codes and investigation guide
+
+`--explain` adds fixed, data-free descriptions only for detected codes. It does not inspect strategy source code, prove causal timing, or give a verified fix. Do not publish aggregate reports without reviewing them.
+
+```sh
+python -m backtest_doctor ledger examples/ledger_bad.csv --explain
+```
+
+| Code | Meaning | Investigation |
+| --- | --- | --- |
+| `AMBIGUOUS_SAME_BAR_EXIT` | Stop and target are both declared hit within one bar. | Use lower-timeframe or execution evidence and document the intrabar priority rule. |
+| `DUPLICATE_TIMESTAMP` | Two or more candle rows share a timestamp. | Check whether duplicate candles represent duplicated imports or legitimate distinct intervals. |
+| `EMPTY_LEDGER` | No declared trade timing rows were supplied. | Provide signal-close, entry, and next-open timestamps from a reproducible trade export. |
+| `EMPTY_OHLCV` | No OHLCV rows were supplied. | Export at least one timestamped candle and verify the input file is not empty. |
+| `FINDING_LIMIT_REACHED` | The diagnostics limit was reached. | Address the first listed failures, then rerun on a bounded subset or corrected export. |
+| `INVALID_CANDLE_GEOMETRY` | OHLC values violate high/low envelope consistency. | Compare the candle to original source data and check adjustment/aggregation procedures. |
+| `INVALID_NUMERIC_FIELD` | A required candle field is not a finite number. | Check numeric formatting, missing values, and exporter conversions. |
+| `INVALID_PRICE_OR_VOLUME` | A price is nonpositive or volume is negative. | Check source adjustments, units, and upstream data quality; do not clamp values blindly. |
+| `INVALID_TIMESTAMP` | A timestamp is invalid or lacks an explicit timezone. | Check the original time source and export timezone-aware ISO timestamps; never assume UTC. |
+| `INVALID_TRADE_RETURN` | A settled trade has an invalid timestamp or return. | Check timezone, return units, and whether the record is settled; do not guess missing returns. |
+| `IRREGULAR_CADENCE` | A positive interval differs from the declared cadence. | Check sessions, exchange downtime, and missing bars; do not fill gaps without evidence. |
+| `LOOKAHEAD_OR_SAME_BAR_ENTRY` | An entry was not strictly after the declared signal bar close. | Reconcile indicator availability, decision timestamp, and execution timing; do not shift timestamps to hide the violation. |
+| `LOW_TRADE_COUNT` | The sample contains fewer than 30 valid trades. | Collect additional genuinely out-of-sample trades before interpreting stability measures. |
+| `MISSING_LEDGER_COLUMN` | A trade timing row is missing a required timestamp field. | Verify the ledger export and expected column names without synthesizing timing evidence. |
+| `MISSING_OHLCV_COLUMN` | A candle row is missing one or more required OHLCV fields. | Verify the exported header and column mapping; do not invent missing prices. |
+| `NEXT_BAR_EXECUTION_VIOLATION` | Declared next-bar timing is inconsistent with the entry. | Check the next executable bar open and ensure entry was not recorded before it. |
+| `NO_VALID_TRADES` | No valid settled trade returns remained after validation. | Check required fields and source export quality before computing performance metrics. |
+| `NON_MONOTONIC_TIMESTAMP` | Candle timestamps did not increase strictly. | Inspect the export ordering and any overlapping data partitions before sorting. |
+| `SHORT_TIME_COVERAGE` | Valid trades span fewer than three distinct calendar months. | Extend the independent observation period; avoid treating a short window as robust evidence. |
+| `SIGNAL_CAUSALITY_NOT_VERIFIED` | The trade-summary CSV does not establish when signals became knowable. | Supply a separately auditable signal-to-fill ledger before making causal claims. |
+| `UNDEFINED_COMPOUNDING_COST_SCENARIO` | A cost-stressed return cannot be compounded as a simple trade proxy. | Inspect return-unit assumptions and cost magnitude; do not interpret the undefined proxy as account NAV. |

backtest_doctor-0.4.0rc4/docs/FRAMEWORK_TRADES.md

@@ -0,0 +1,45 @@
+# Framework trade-export CSV adapters (experimental)
+
+The `import-trades` mode audits **closed trade return summaries**, using three explicitly documented CSV dialects. It is offline, reads one local CSV, and emits only aggregate diagnostics. It does not run the originating backtesting engine, execute strategies, open archives or network connections, and cannot verify causal signal timing from these fields.
+
+## Quickstart with synthetic fixtures
+
+Run from a clean checkout after `python -m pip install --no-deps .`:
+
+```sh
+python -m backtest_doctor import-trades examples/backtesting_py_synthetic.csv --framework backtesting-py
+python -m backtest_doctor import-trades examples/vectorbt_synthetic.csv --framework vectorbt
+python -m backtest_doctor import-trades examples/freqtrade_csv_synthetic.csv --framework freqtrade-csv
+```
+
+Each command should return `WARN` (and exit 0) because the fixtures contain only three **invented** closed trades and signal/entry evidence is unavailable. Use `--fail-on-warn` to enforce strict CI. To add an *additional hypothetical* 20 basis points of per-trade cost stress:
+
+```sh
+python -m backtest_doctor import-trades examples/vectorbt_synthetic.csv --framework vectorbt --additional-cost-bps 20
+```
+
+### CSV contract (case-sensitive)
+
+| `--framework` | Required columns | Return meaning |
+| --- | --- | --- |
+| `backtesting-py` | `ExitTime`, `ReturnPct` | `ReturnPct` is a **fraction** from `Backtest.run()['_trades']`, not percent points |
+| `vectorbt` | `Exit Timestamp`, `Return`, `Status` | `Return` is a **fraction** from `Portfolio.trades.records_readable`; `Status` must be `Closed` |
+| `freqtrade-csv` | `close_date`, `profit_ratio`, `is_open` | `profit_ratio` is a **fraction** from a user-created CSV extraction; `is_open` must explicitly be false |
+
+**All timestamps must include an explicit timezone** (`Z` or `+00:00`), and all rows must be settled. Inputs with naive timestamps, missing required columns, open trades, nonfinite returns, or invalid values fail closed with a redacted error. This is intentionally stricter than some native DataFrame exports. Add timezone information at the source only when it is independently known; never silently infer UTC.
+
+**Important: no native Freqtrade ZIP/JSON support.** Freqtrade's current official backtesting output uses a ZIP containing strategy and config material. Do not feed that archive into this tool or publicly upload it. `freqtrade-csv` supports only an explicitly prepared CSV subset with the three columns above; it is not an endorsement of an upstream CSV export format.
+
+For `backtesting.py`, obtain a DataFrame with `stats['_trades']` (the `ReturnPct` field is fractional). For `vectorbt`, use `portfolio.trades.records_readable`; the timestamps must be actual timezone-aware datetimes, not positional integer bar indices. Both frameworks use public APIs that may change; verify these schemas when upgrading.
+
+### Fee accounting and privacy
+
+Existing framework returns **may already include commissions or funding**. The `cost_0bps` scenario preserves each reported return unchanged; `--additional-cost-bps N` is an **extra hypothetical stress**, not reconstructed trading costs. Do not interpret the result as gross pre-fee performance or independently measured account NAV. Results are simplified sequential trade proxies; overlapping positions and cash flows are not modeled.
+
+Only **synthetic** examples are committed. Real trade exports may contain tickers, private strategies, account fields, trade times or returns; keep them on machines and CI runners authorized for that data. The tool does not print raw values or paths, but *aggregate* performance can still be sensitive. The GitHub Action runs on GitHub-hosted runners: do not upload private exports just to test this feature.
+
+References to upstream formats:
+- [Backtesting.py source: `_stats.py`](https://github.com/kernc/backtesting.py/blob/master/backtesting/_stats.py)
+- [Vectorbt trade records](https://vectorbt.dev/api/portfolio/trades/)
+- [Freqtrade trade fields](https://www.freqtrade.io/en/stable/advanced-backtesting/)
+- [Freqtrade ZIP output caveat](https://www.freqtrade.io/en/stable/backtesting/)

backtest_doctor-0.4.0rc4/docs/LIMITATIONS.md

@@ -0,0 +1,10 @@
+# What Backtest Doctor does not prove
+
+**A passed audit is not proof of a legitimate trading edge.** Input fields are supplied by the caller and are not independently sourced from a point-in-time market-data vendor.
+
+- `ohlcv`: validates local structural consistency, not completeness of the historical investible universe, official delisting records, exchange downtime or vendor accuracy.
+- `ledger`: checks declared signal-bar-close/entry/next-bar ordering. It does not inspect strategy AST, prove actual fillability, reconstruct liquidity, detect every repainting indicator or verify exchange trades.
+- `stability`: uses reported per-trade gross return fractions, simple per-trade cost subtraction and a sequential, non-overlapping, equal-equity proxy. It does not reconstruct real leverage, borrow, funding, portfolio NAV, concurrent positions or actual costs.
+- `bundle`: aggregates independent diagnostics. A passing bundle does not prove that the three CSVs refer to the same trades, same universe, or same sampling window.
+
+Reports omit raw input values, filenames, symbols and account details. Rows and aggregate metrics may still be sensitive in some circumstances: review before distribution. The tool assumes the local filesystem and Python environment are trustworthy.

backtest_doctor-0.4.0rc4/docs/PYPI_PUBLISHING.md

@@ -0,0 +1,20 @@
+# PyPI publishing: guarded, manual, no permanent tokens
+
+**Current state:** PyPI publication is not part of the GitHub prerelease. Do not promise `pip install backtest-doctor` until the PyPI project page and an installation from that index have been independently verified.
+
+The repository contains a guarded workflow `.github/workflows/publish-pypi.yml`. It never runs from ordinary pushes or PRs. It requires manual execution against a matching `vX.Y.Z` **Git tag**, an explicit `PUBLISH` acknowledgement, a successful source/artifact gate, and a GitHub Environment named `pypi`. It uses OIDC Trusted Publishing rather than credentials placed in repository secrets or files.
+
+## One-time setup by the PyPI account owner
+
+1. Sign in to [PyPI](https://pypi.org/), preferably with two-factor authentication, and create a pending publisher for package `backtest-doctor`, **if that name is available**.
+2. Set **Owner** = `suguobin2021`, **Repository** = `backtest-doctor`, **Workflow filename** = `publish-pypi.yml`, and **Environment name** = `pypi` (exactly).
+3. In GitHub repository settings, create the environment `pypi` with release branch/tag restrictions as appropriate and required reviewer protection if available. Never create a PyPI long-lived token just for this workflow.
+4. Prepare a **new** version tag from reviewed and CI-green source. Do not republish or move `v0.4.0rc1` and do not tag an unreviewed commit.
+5. Run the workflow manually on that tag, enter `PUBLISH`, and inspect the release checks and upload logs. A no-op dry run can instead use `DRY_RUN`.
+6. After publication, verify the package name, project owner, files and SHA256 on PyPI, then install it in a fresh environment on at least two Python versions and run the synthetic demos. Only then update README.
+
+**Critical:** adding the workflow does not enroll a PyPI publisher, set up GitHub environment protections, or prove domain/package ownership. These are separate account-level actions. Never claim that a failed upload is a successful publication.
+
+Official references:
+- https://docs.pypi.org/trusted-publishers/using-a-publisher/
+- https://packaging.python.org/en/latest/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/

backtest_doctor-0.4.0rc4/docs/QUICKSTART.md

@@ -0,0 +1,55 @@
+# Quickstart: prove the CLI works without real trading data
+
+All inputs in this guide are **synthetic**. No account, trading system, private strategy, or market-data export is needed. The tool operates offline and does not transmit your CSV rows.
+
+## 1. Install from the public source
+
+Requires Python 3.10 or newer and Git. On macOS/Linux, run:
+
+```sh
+git clone https://github.com/suguobin2021/backtest-doctor.git
+cd backtest-doctor
+python3 -m venv .venv
+.venv/bin/python -m pip install --no-deps .
+.venv/bin/python -m backtest_doctor --version
+```
+
+On Windows PowerShell, replace `python3` with `py -3` and each `.venv/bin/python` with `.venv/Scripts/python.exe`. Do not upload your own CSV files to a third-party service to try this demo.
+
+A versioned GitHub Release wheel is also available; PyPI installation is not advertised until an actual published PyPI package has been verified.
+
+## 2. Pass an OHLCV structure check
+
+```sh
+.venv/bin/python -m backtest_doctor ohlcv examples/ohlcv_good.csv
+```
+
+Expect a JSON result containing `"status":"PASS"` and exit code **0**. This means the supplied rows passed **implemented** checks only.
+
+## 3. Detect an intentionally invalid fill
+
+```sh
+.venv/bin/python -m backtest_doctor ledger examples/ledger_bad.csv
+```
+
+Expect `"status":"FAIL"` and exit code **1**. A non-zero exit is the **expected result for this synthetic negative test**, not an installation error. If you want a successful ledger sample, use `examples/ledger_good.csv`.
+
+## 4. Generate an offline HTML report
+
+```sh
+.venv/bin/python -m backtest_doctor bundle \
+  --ohlcv-file examples/ohlcv_good.csv \
+  --ledger-file examples/ledger_good.csv \
+  --stability-file examples/stability_demo.csv \
+  --html local-audit-report.html
+```
+
+Expect `"status":"WARN"` with exit **0**: there are only four illustrative trades, so sample-size warnings are intentional. The HTML file is self-contained and includes aggregate findings rather than raw CSV rows. The CLI will not overwrite an existing output file. Do not publish the report without reviewing its aggregated information.
+
+Pass `--fail-on-warn` if warnings must fail your own CI pipeline.
+
+## 5. Know the limits
+
+The tool checks declared timestamps and elementary candle structure. It does not execute your strategy, prove actual fillability, detect all look-ahead biases, or establish a profitable strategy. The example returns are invented.
+
+See [Limitations](LIMITATIONS.md) and [Security](../SECURITY.md).

backtest_doctor-0.4.0rc4/docs/RELEASE_CHECKLIST.md

@@ -0,0 +1,34 @@
+# Backtest Doctor release checklist
+
+## Safety (must pass)
+
+- [x] Code and fixtures are created from public-source software and synthetic examples only.
+- [x] No access to or copying from private private trading, exchange-data, or research databases.
+- [x] A clean, new history is prepared; no private repository history is imported.
+- [x] Source + sdist + wheel allowlist checks, secret/path scans, no network/runtime-code-execution AST gate.
+- [x] Public GitHub tree and v0.4.0rc1 prerelease were independently verified on 2026-11-02.
+- [ ] Enable GitHub branch protection (requires repository administrator setting).
+
+## Compatibility
+
+- [x] Python 3.10 and 3.12 on Linux: V0.3 wheel 52/52 tests, earlier stage.
+- [x] GitHub CI for 3.10 / 3.11 / 3.12 / 3.13 completed on 2026-11-02; ongoing checks must be green before another release.
+- [x] Windows and macOS GitHub CI completed successfully on 2026-11-02.
+
+## Distribution
+
+- [x] GitHub repo created and initial audited public-source commit pushed.
+- [x] v0.4.0rc1 GitHub prerelease attached to audited commit.
+- [ ] PyPI package ownership/name availability checked by authenticated publisher.
+- [ ] PyPI trusted publishing configured for exact repo/workflow before uploading.
+- [ ] Only after a verified package URL exists, change README install instruction from conditional to unconditional.
+
+GitHub publication and PyPI publication are separate milestones. Fail closed: no credential disclosure, no auto-publish via personal access tokens embedded in config.
+
+## New P0 gates
+
+- [ ] Publish stable package only from a reviewed matching Git tag.
+- [ ] PyPI Trusted Publisher registered by account owner (no long-lived token).
+- [ ] PyPI published files and independent installation inspected.
+- [x] Offline source allowlist + wheel/sdist content gate implemented in `tools/verify_release.py`.
+- [x] Beginner synthetic guide added in `docs/QUICKSTART.md`.

backtest_doctor-0.4.0rc4/examples/backtesting_py_synthetic.csv

@@ -0,0 +1,4 @@
+EntryTime,ExitTime,ReturnPct,EntryPrice,ExitPrice,Tag
+2026-01-01T00:00:00Z,2026-01-04T00:00:00Z,0.02,100,102,SYNTHETIC
+2026-02-01T00:00:00Z,2026-02-04T00:00:00Z,-0.01,100,99,SYNTHETIC
+2026-03-01T00:00:00Z,2026-03-04T00:00:00Z,0.015,100,101.5,SYNTHETIC

backtest_doctor-0.4.0rc4/examples/columns_synthetic.json

@@ -0,0 +1,5 @@
+{
+  "ohlcv": {"timestamp":"Date","open":"Open","high":"High","low":"Low","close":"Close","volume":"Volume"},
+  "ledger": {"signal_bar_close":"SignalClose","next_bar_open":"NextOpen","entry_time":"Entered"},
+  "stability": {"exit_time":"Exited","gross_return":"GrossReturn"}
+}

backtest_doctor-0.4.0rc4/examples/freqtrade_csv_synthetic.csv

@@ -0,0 +1,4 @@
+close_date,profit_ratio,is_open,pair
+2026-01-04T00:00:00Z,0.02,false,DEMO/USDT
+2026-02-04T00:00:00Z,-0.01,false,DEMO/USDT
+2026-03-04T00:00:00Z,0.015,false,DEMO/USDT

backtest_doctor-0.4.0rc4/examples/ledger_alias.csv

@@ -0,0 +1,2 @@
+SignalClose,NextOpen,Entered
+2026-01-01T00:01:00Z,2026-01-01T00:01:00.000001Z,2026-01-01T00:01:00.000001Z

backtest_doctor-0.4.0rc4/examples/ledger_bad.csv

@@ -0,0 +1,2 @@
+signal_bar_close,next_bar_open,entry_time,stop_hit,target_hit
+2026-01-01T00:01:00Z,2026-01-01T00:01:00.000001Z,2026-01-01T00:00:30Z,true,true

backtest_doctor-0.4.0rc4/examples/ledger_good.csv

@@ -0,0 +1,2 @@
+signal_bar_close,next_bar_open,entry_time,stop_hit,target_hit
+2026-01-01T00:01:00Z,2026-01-01T00:01:00.000001Z,2026-01-01T00:01:00.000001Z,false,false

backtest_doctor-0.4.0rc4/examples/ohlcv_alias.csv

@@ -0,0 +1,3 @@
+Date,Open,High,Low,Close,Volume
+2026-01-01T00:00:00Z,100,102,99,101,10
+2026-01-01T00:01:00Z,101,103,100,102,9

backtest_doctor-0.4.0rc4/examples/ohlcv_bad.csv

@@ -0,0 +1,3 @@
+timestamp,open,high,low,close,volume
+2026-01-01T00:00:00Z,100,99,98,101,10
+2026-01-01T00:00:00Z,101,103,100,102,12

backtest_doctor-0.4.0rc4/examples/ohlcv_good.csv

@@ -0,0 +1,4 @@
+timestamp,open,high,low,close,volume
+2026-01-01T00:00:00Z,100,102,99,101,10
+2026-01-01T00:01:00Z,101,103,100,102,12
+2026-01-01T00:02:00Z,102,104,101,103,11

backtest_doctor-0.4.0rc4/examples/stability_alias.csv

@@ -0,0 +1,5 @@
+Exited,GrossReturn
+2026-01-01T00:00:00Z,0.020
+2026-02-01T00:00:00Z,-0.010
+2026-03-01T00:00:00Z,0.015
+2026-04-01T00:00:00Z,-0.005

backtest_doctor-0.4.0rc4/examples/stability_demo.csv

@@ -0,0 +1,5 @@
+exit_time,gross_return
+2026-01-01T00:00:00Z,0.020
+2026-02-01T00:00:00Z,-0.010
+2026-03-01T00:00:00Z,0.015
+2026-04-01T00:00:00Z,-0.005

backtest_doctor-0.4.0rc4/examples/vectorbt_synthetic.csv

@@ -0,0 +1,4 @@
+Entry Timestamp,Exit Timestamp,Return,Status,Direction
+2026-01-01T00:00:00Z,2026-01-04T00:00:00Z,0.02,Closed,Long
+2026-02-01T00:00:00Z,2026-02-04T00:00:00Z,-0.01,Closed,Short
+2026-03-01T00:00:00Z,2026-03-04T00:00:00Z,0.015,Closed,Long

backtest_doctor-0.4.0rc4/pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "backtest-doctor"
+version = "0.4.0rc4"
+description = "Offline backtest integrity checks for OHLCV, trade timing, and stability"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{name = "suguobin2021"}]
+dependencies = []
+readme = "README.md"
+
+[project.scripts]
+backtest-doctor = "backtest_doctor.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]