feat: add Quant OS A-share baseline
This commit is contained in:
@@ -0,0 +1,252 @@
|
||||
# Quant OS cross-engine consistency contract
|
||||
|
||||
“本地、聚宽、QMT、Qlib 都能跑”不等于四条净值曲线必须逐点相同。跨引擎
|
||||
一致性按层比较：相同信息集应产生相同计算；平台特有的日历、价格语义和成交
|
||||
差异必须被记录、归因和限制。
|
||||
|
||||
## 1. Comparison levels
|
||||
|
||||
| Level | Compared artifact | Same canonical input required | Pass rule |
|
||||
| --- | --- | --- | --- |
|
||||
| L0 | Source/config manifest | Git state、portable-core hash、strategy/model version、symbol map | Exact |
|
||||
| L1 | Data/universe | `as_of`、sessions、symbols、PIT membership、raw/factor/declared adjusted prices、tradability | Exact values or explicit provider reason |
|
||||
| L2 | Signal | symbol、horizon、lookback/skip、score、model bundle | Exact symbol set；numeric tolerance below |
|
||||
| L3 | Target | target weight/quantity、frozen/sellable state | weight tolerance；exact lot quantity |
|
||||
| L4 | Order intent | ID、side、quantity、limit、type、TIF、timing、reason | Identical broker snapshot/rules 时 exact |
|
||||
| L5 | Order/fill/portfolio | status、fills、fees、cash、positions | Semantic invariants；相同 fill fixture 才要求 exact |
|
||||
| L6 | Performance | return、turnover、drawdown、cost | Diagnostic；不能代替 L1—L5 |
|
||||
|
||||
只比较 L6 不会通过 G9。Alpha158/LightGBM 与 portable momentum 是不同 model
|
||||
spec，本来就不是 L2 peer；可做研究比较，不能冒充同策略 parity。
|
||||
|
||||
## 2. Canonical snapshot is the L1 handoff
|
||||
|
||||
JQData ingestion 通过官方 `get_bars` 保存：
|
||||
|
||||
- raw `open/high/low/close/volume/money`；
|
||||
- `factor`、`pre_close`、`high_limit`、`low_limit`、`paused`；
|
||||
- 每个 member-date 的 PIT `is_st`；
|
||||
- 每个交易日的历史指数成员。
|
||||
|
||||
快照必须保持 `adjustment=none`，front-adjusted feature history 在每个
|
||||
decision `as_of` 时由当时已保存的 raw close + factor 构造。这样执行价仍是
|
||||
raw，且后来的 factor 不能改写旧决策。
|
||||
|
||||
L1 verifier 不只比文件 hash，还要：
|
||||
|
||||
1. 拒绝 incomplete marker；
|
||||
2. 要求目录是 manifest 声明的精确 artifact 集；
|
||||
3. 重建每个 bar/membership 领域对象；
|
||||
4. 重算质量统计、内容 hash 与 `data_version`；
|
||||
5. 拒绝重复键、非法 OHLC、停牌非零量、非法限价、缺失 factor 或非布尔/
|
||||
缺失 `is_st`；
|
||||
6. 拒绝 retrieval 当日仍未在 Asia/Shanghai 24:00 完成的日线。
|
||||
|
||||
验证入口：
|
||||
|
||||
```bash
|
||||
PYTHONPATH=src:. python -c \
|
||||
"from quant60.data_snapshot import verify_data_snapshot; verify_data_snapshot('data/snapshots/csi500-2024/manifest.json')"
|
||||
```
|
||||
|
||||
`snapshot-backtest` 和 `snapshot-decision` 都先通过该 verifier。它们能证明
|
||||
同一个 snapshot 的本地可重放性，但在真实授权 JQData run 和平台导出前，
|
||||
不能证明 provider entitlement 或 G9。
|
||||
|
||||
## 3. Required run manifest
|
||||
|
||||
每个 comparison 至少保存：
|
||||
|
||||
```json
|
||||
{
|
||||
"run_id": "unique-id",
|
||||
"engine": "local|joinquant|qmt_builtin|qmttools|xttrader|qlib",
|
||||
"mode": "fixture|provider_snapshot|backtest|simulation|shadow|live",
|
||||
"git_commit": "commit-or-DIRTY",
|
||||
"portable_core_sha256": "sha256",
|
||||
"strategy_or_model_version": "immutable-id",
|
||||
"python_version": "major.minor.patch",
|
||||
"platform_version": "value-or-unknown",
|
||||
"config_hash": "sha256",
|
||||
"data_version": "immutable-id",
|
||||
"rules_version": "immutable-id",
|
||||
"timezone": "Asia/Shanghai",
|
||||
"signal_as_of": "ISO-8601 timestamp",
|
||||
"last_feature_bar": "ISO-8601 date-or-time",
|
||||
"first_executable_time": "ISO-8601 timestamp",
|
||||
"price_adjustment": "raw|pre|post|front_ratio|PIT_FRONT_FROM_RAW_AND_FACTOR",
|
||||
"fill_model": "declared-name",
|
||||
"evidence_class": "fake|synthetic|provider-snapshot|real-platform|broker"
|
||||
}
|
||||
```
|
||||
|
||||
unknown platform version 可用于 smoke，但阻止 release certification。
|
||||
|
||||
本地 execution/provider snapshot run 保存后执行：
|
||||
|
||||
```bash
|
||||
PYTHONPATH=src:. python -m quant60 verify-manifest \
|
||||
artifacts/<run-id>/manifest.json
|
||||
```
|
||||
|
||||
它检查 incomplete marker、精确 artifact set/hash、ledger chain/head、
|
||||
report/manifest identity、saved/current source/schema aggregate 和 payload
|
||||
schema。snapshot decision 使用：
|
||||
|
||||
```bash
|
||||
PYTHONPATH=src:. python -m quant60 verify-snapshot-decision \
|
||||
artifacts/<decision-id>/manifest.json
|
||||
```
|
||||
|
||||
## 4. Numeric and semantic tolerances
|
||||
|
||||
对传入 `portable_core.py` 的同一固定 close arrays：
|
||||
|
||||
| Field | Tolerance |
|
||||
| --- | --- |
|
||||
| canonical symbol、rank、selected set | Exact |
|
||||
| momentum score | absolute error ≤ `1e-12` |
|
||||
| target weight | absolute error ≤ `1e-10` |
|
||||
| target quantity | Exact integer |
|
||||
| order delta | Exact signed integer |
|
||||
|
||||
真实 provider 数据先比较输入数组。不同复权约定、停牌填充、成分股日期或
|
||||
feature cutoff 导致的 score 差异是 L1 failure，不是浮点噪声。
|
||||
|
||||
本地货币 ledger 按配置的 currency quantum 比较。hosted NAV 只有在 bars、
|
||||
company actions、fees 和 fill events 都相同时才要求相同；否则必须分类：
|
||||
|
||||
- `input-price difference`；
|
||||
- `timing difference`；
|
||||
- `tradability/fill difference`；
|
||||
- `explicit-fee difference`；
|
||||
- `residual unexplained difference`。
|
||||
|
||||
residual 必须为零或低于 release-specific bound，不能静默并入 slippage。
|
||||
|
||||
## 5. Clock alignment
|
||||
|
||||
canonical weekly clock 是 ISO 周第一实际交易日完整 close，紧接着下一实际
|
||||
交易日 open。它不是固定星期几；单交易日长假周会自然跨到下一 ISO 周。
|
||||
|
||||
comparison key 必须包含：
|
||||
|
||||
```text
|
||||
(signal_as_of, last_feature_bar, first_executable_time, adjustment_mode)
|
||||
```
|
||||
|
||||
任一元素不同就不是 strict peer，只能做诊断 comparison。
|
||||
|
||||
本地 snapshot backtest 使用：
|
||||
|
||||
- exact daily PIT membership；
|
||||
- decision date raw close + factor 构造 point-in-time front-adjusted signal；
|
||||
- next session raw open 执行；
|
||||
- provider daily pause/limit/pre-close；
|
||||
- provider daily PIT `is_st`：ST 不新买，已持有 ST 只卖；
|
||||
- prior-session volume capacity。
|
||||
|
||||
JoinQuant/QMT 必须导出相同输入或其 hash 才能进入 L2—L4 strict comparison。
|
||||
|
||||
## 6. Platform interpretation and current facts
|
||||
|
||||
- **Local**：固定 fixture 的 deterministic contract oracle，不自动等于市场
|
||||
真相。
|
||||
- **JoinQuant**：以前一交易日查询 PIT index/ST，以批量 `history` 读取完成
|
||||
日线，并显式设置费用、滑点和 10% 参与率；必须导出实际 close
|
||||
arrays/hash、plan、orders/fills 和平台配置。本地 fake harness 只证明
|
||||
wiring。2026-07-26 已完成一次 2024 全年真实 hosted smoke，运行日志无
|
||||
ERROR；但尚未导出上述相同输入与分层结果，所以它是 runtime evidence，
|
||||
不是 strict peer/G9 证据。
|
||||
- **QMT built-in / qmttools**：共享 bundle 但生命周期不同，均硬
|
||||
backtest-only；固定中证 500 benchmark，以历史 timetag 查询 PIT 成分/ST。
|
||||
built-in 的 10% 最大成交量占比需要 QMT UI 设置并取证，qmttools
|
||||
程序化传入。真实 QMT 环境尚未运行。qmttools 把 transfer fee 折入
|
||||
commission，minimum commission/fill 行为是声明差异。
|
||||
- **XtTrader**：比较 broker snapshot、order intent 与 normalized callback。
|
||||
当前已有只读 HMAC 账户绑定、broker observation/snapshot 和 exact
|
||||
shadow-plan verifier，但只有 fake broker contract，没有真实 shadow。
|
||||
- **Qlib momentum**：`pyqlib==0.9.7` 的 native fixture 已真实运行，产生
|
||||
24 条 signal；结果保存 signal/report hash、表边界和从 report 重算的
|
||||
portfolio 指标。它证明 runtime/path 可执行，不证明真实市场或 L3/L4。
|
||||
- **Qlib Alpha158/LightGBM**：fixture 上已真实完成 model + Recorder。
|
||||
runner 自动以 `setdefault` 设置 `MLFLOW_ALLOW_FILE_STORE=true` 以兼容本地
|
||||
MLflow file store，并读取 portfolio report 保存 hash、边界和重算指标。
|
||||
两股票 synthetic 性能没有投资意义，且该模型不是 portable momentum 的
|
||||
parity peer。
|
||||
- **Mock parity exporter**：当前能逐层比较 JoinQuant/QMT fake wrapper 的
|
||||
score、weight、quantity、delta，并校验 source hash。它明确是
|
||||
`mock_contract_only`、`real_platform_pass=false`、`gate_credit=[]`。
|
||||
|
||||
## 7. Difference reason codes
|
||||
|
||||
必须使用枚举 reason code，不能只写“平台差异”：
|
||||
|
||||
```text
|
||||
CALENDAR
|
||||
SYMBOL_MAP
|
||||
UNIVERSE
|
||||
MISSING_BAR
|
||||
SUSPENSION_FILL
|
||||
PRICE_ADJUSTMENT
|
||||
AS_OF_CLOCK
|
||||
ROUNDING
|
||||
FEE_SCHEDULE
|
||||
PRICE_LIMIT
|
||||
T_PLUS_ONE
|
||||
VOLUME_LIMIT
|
||||
FILL_MODEL
|
||||
BROKER_STATE
|
||||
FLOAT_TOLERANCE
|
||||
UNEXPLAINED
|
||||
```
|
||||
|
||||
symbol set、signal、target、order intent、cash 或 position 出现任何
|
||||
`UNEXPLAINED` 都阻止 release。
|
||||
|
||||
## 8. Runnable comparison support
|
||||
|
||||
mock-only exporter：
|
||||
|
||||
```bash
|
||||
PYTHONPATH=src:. python tools/export_mock_parity.py \
|
||||
export --output artifacts/mock-parity/report.json
|
||||
PYTHONPATH=src:. python tools/export_mock_parity.py \
|
||||
verify artifacts/mock-parity/report.json
|
||||
```
|
||||
|
||||
Qlib native momentum fixture：
|
||||
|
||||
```bash
|
||||
python3.12 -m venv .venv-qlib312
|
||||
source .venv-qlib312/bin/activate
|
||||
python -m pip install -r requirements/research-py312.txt
|
||||
python tools/build_qlib_tiny_fixture.py artifacts/qlib-fixture --days 80
|
||||
PYTHONPATH=src:. python -m platforms.qlib_runner \
|
||||
--provider-uri artifacts/qlib-fixture \
|
||||
--market csi300 --benchmark SH000300 \
|
||||
--start 2024-02-01 --end 2024-04-19 \
|
||||
--lookback 20 --topk 1 --n-drop 1 --rebalance weekly \
|
||||
--output-json artifacts/qlib-native/result.json
|
||||
```
|
||||
|
||||
两者都不是 G9 的真实平台证据。
|
||||
|
||||
## 9. What counts toward G9
|
||||
|
||||
| Evidence | Counts toward G9? |
|
||||
| --- | --- |
|
||||
| symbol/unit tests、fake JoinQuant/QMT harness | Supporting only |
|
||||
| mock parity exporter | No；contract regression only |
|
||||
| local snapshot twice with same hash | Supporting G7/L1 only |
|
||||
| Qlib 24-signal synthetic fixture smoke | Runtime evidence only |
|
||||
| Qlib Alpha158 synthetic Recorder smoke | Research runtime evidence only |
|
||||
| real JoinQuant export vs local canonical run | Yes，覆盖的 layers/dates |
|
||||
| licensed qmttools run with saved version/result | Yes，覆盖的 layers |
|
||||
| XtTrader shadow using real broker snapshot | Yes，pre-trade/order semantics |
|
||||
| ≥20 trading days QMT shadow, zero unexplained differences | 文章 G9 必需 |
|
||||
|
||||
真实 JoinQuant smoke 已运行；QMT 和 broker shadow 尚未运行，而且
|
||||
JoinQuant 仍缺同输入导出与 local peer，所以 G9 继续为 `not_passed`。
|
||||
状态权威是
|
||||
[`gate_scorecard.json`](../gate_scorecard.json)。
|
||||
Reference in New Issue
Block a user