# Quant OS platform capability matrix

“有入口”与“已在目标平台验证”必须分开。Quant OS 共享的是冻结计算合同，
不是四个平台完全相同的时钟、行情和成交模型。

| Path | Intended use | Runtime / prerequisite | Current verified fact | Missing release evidence |
| --- | --- | --- | --- | --- |
| Local synthetic execution | 确定性事件回测、ledger/replay | Python ≥3.10，无账号 | 标准库套件、smoke + exact manifest verifier 可运行 | synthetic 不代表真实市场/收益 |
| Local synthetic research | 五层 vertical slice：Universe/Ridge Alpha/risk+cost Portfolio/post-risk/reference Execution | Python ≥3.10，无账号 | 冻结 model bundle、TargetPackageV1、layer trace + manifest verifier 可运行；风险/成本扰动必须改变 target | 仍是 synthetic；当前只接对角风险与 deterministic optimizer，未做授权长样本 OOS |
| JQData ingestion | 授权数据到 canonical immutable snapshot | `jqdatasdk==1.9.8` + 授权账号 | fake-provider 测试覆盖 raw/factor/pre-close/limits/paused/PIT `is_st`/membership、24:00 完整收盘约束和语义 verifier | 尚未登录真实账号保存快照、许可与 lineage |
| Snapshot local backtest | PIT membership 的 provider-data 本地回测 | semantic verifier 通过的 snapshot | `snapshot-backtest` 复用 production decision path，输出普通 run manifest | 尚无授权真实 snapshot；仍是本地 fill model |
| Snapshot decision | 某决策日 Signal/Target/Order Delta | snapshot + equity 或完整 broker snapshot | fail-closed broker state 与 exact decision manifest verifier 已实现 | 未接真实账户 snapshot，未冻结生产模型 |
| Colab | clone、测试、bundle、本地两条 synthetic 链；可选 JQData/Qlib | Colab runtime | notebook 已可本地逐 cell 执行 | 可选账号/依赖 cell 仍需运行时授权；不是平台证据 |
| JoinQuant local harness | wrapper API 合同 | Python ≥3.10，无账号 | 动量 smoke 与 TargetPackage 消费模式均有 fake lifecycle；目标包缺失/篡改不回退 | 不证明 JoinQuant |
| JoinQuant hosted bundle | hosted backtest | JoinQuant 登录/数据权限 | 动量 smoke 的真实 2024 全年 run 已完成；FINAL4 的单个 synthetic-research TargetPackage 已在真实 hosted 环境按 `day_open` 命中并产生 3 单/3 fill | 只观察 execution consumer；无授权真实长样本/OOS、上游四层 hosted 执行、QMT peer 或逐层真实数据 parity |
| QMT local harness | built-in wrapper 合同 | Python ≥3.10，无账号 | Python 3.6 source、`ContextInfo` 回滚模拟、动量 smoke 与 TargetPackage 合同 | 不证明 QMT |
| QMT built-in bundle | GUI backtest-only | 授权 QMT 客户端/历史数据 | 两种模式都硬限制 backtest；TargetPackage 模式不重算上游四层；模块全局 `g` | 尚无 TargetPackage 真实 QMT run/export；10% GUI 配置和执行时钟待取证 |
| qmttools runner | native-Python QMT backtest/history | 券商分发 `xtquant` + 已登录 terminal | 固定中证 500/10% 参与率、参数、只读 preflight 和 hard backtest/history 合同已测 | 尚无专有运行时实跑 |
| XtTrader read-only shadow | 账户绑定 target-diff 与 broker observation | MiniQMT/QMT、账户查询权限、既有本地 HMAC key | HMAC 账户绑定 + authenticated evidence envelope、decision/observation semantic replay、资产/持仓/委托/成交恒等式、fail-closed exact verifier 与 fake broker 合同 | HMAC 不是 broker attestation；仍缺官方 query 失败/空结果合同及 callback/restart；Baseline 60 至少 20 个交易日，Production 80 当前缺口为同一冻结候选至少 60 个交易日；not live-ready |
| Qlib native momentum | signal/model research | CPython 3.12 + exactly `pyqlib==0.9.7` | 真实本地 fixture 成功，24 signal；保存 signal/report hash、表边界和重算 portfolio 指标 | synthetic 两股票；无真实数据/OOS，无 L3/L4 parity |
| Qlib Alpha158/LightGBM | model fit + Recorder workflow | 同上 + LightGBM/MLflow stack | 真实 fixture 完成 model/Recorder；读取 portfolio report，保存表 hash、边界、重算指标与 artifact path | synthetic 两股票性能无意义；真实 provider/OOS 和冻结模型缺失 |
| Tushare local → Qlib | live mirror 只读盘点、scoped release、不可变 provider 与本地研究 | 同上 + `pyarrow==24.0.0`；本地镜像 | selected jobs double verified、仍 latest；独立 lineage 验证 221 jobs×6 fields、mismatch 0、converter current true；v2 verifier 通过：1,111 instruments、1,942 sessions、1,975,455 rows；97 observed/96 effective snapshots 严格 500 成分、次日生效；双次 JSON byte-identical | event-time/保守次日生效 PIT 近似，不是严格 knowledge-time PIT；不同 start 的首观测锚 provider 不可直接拼接；research-only、`gate_credit=[]`；ST/统一 9.5% 仍缺 |
| Mock parity exporter | JoinQuant/QMT wrapper 的 L2—L4 合同回归 | Python ≥3.10 | `mock_contract_only`、`real_platform_pass=false`、`gate_credit=[]` | 不计 G9；必须换成真实平台导出 |

G1—G10 当前都未通过。JoinQuant TargetPackage run 支持且只支持
`execution.real_platform_observed=true`；输入仍是 `synthetic-research`，
Universe/Alpha/Portfolio/Risk 的真实平台观察均为 false。它与旧 momentum
smoke、Qlib fixture 一样，不是市场有效性或跨平台 Gate 通过证据。

## Stable strategy boundary

`portable-momentum-v1` 当前只作为 smoke 冻结：

- canonical symbol normalization；
- momentum score/rank；
- capped target weights；
- lot-rounded target quantity；
- T+1/sellable-aware order delta。
- 科创板 200 股最小申报、余额一次性卖清与 hosted 最坏价保护。

本地 Ridge 已能冻结为 versioned model bundle，并通过
`TargetPackageV1` 把 post-risk 权重移交给 JoinQuant/QMT；平台不需要、也
不应重新运行训练栈。一个 synthetic 包已通过真实 JoinQuant execution
consumer，但没有授权真实 OOS、真实校准、多期逐层 parity 和 QMT peer，
仍不能称为已部署 champion。

Qlib 的单一 `limit_threshold` 是市场级近似，不能表达逐日板块/ST 限制；
因此它只参加 L1/L2 和诊断 L6。XtTrader mutation 边界目前只接受 `.SH`
和 `.SZ`，北交所 symbol conversion 覆盖不等于北交所实盘覆盖。

## Platform terms

- **QMT built-in**：`init` / `handlebar` 在 QMT 管理的 Python 3.6 环境执行。
  用户状态放在模块全局 `g`，避免 `ContextInfo` 用户属性在下个
  `handlebar` 回滚。
- **qmttools**：native Python 通过 `run_strategy_file` 驱动策略文件。
  supplied runner 固定 backtest/history，不能等同于 XtTrader OMS。
- **XtTrader**：连接 MiniQMT 的查询、报单/撤单与异步推送 API。存在 guarded
  mutation path 不代表券商认证或 live-ready；本项目对 operator 暴露的
  shadow CLI 严格只读，没有报单/撤单命令。
- **fake harness**：函数名和生命周期匹配的本地对象，只用于合同回归。
- **Qlib Recorder**：研究 artifact 记录机制。两股票 synthetic Recorder
  成功不等于模型有投资价值。

## Minimum verification commands

从 `quant-os` 项目根目录运行：

```bash
# 核心和 Colab 默认流程
make local

# JQData 快照与 semantic verifier（会交互式无回显读取密码）
PYTHONPATH=src:. python tools/jqdata_snapshot.py \
  --index 000905.XSHG --start 2024-01-02 --end 2024-12-31 \
  --output data/snapshots/csi500-2024
PYTHONPATH=src:. python -c \
  "from quant60.data_snapshot import verify_data_snapshot; verify_data_snapshot('data/snapshots/csi500-2024/manifest.json')"

# 快照回测和决策
PYTHONPATH=src:. python -m quant60 snapshot-backtest \
  --snapshot data/snapshots/csi500-2024/manifest.json \
  --config configs/baseline.json --output artifacts/csi500-2024-backtest
PYTHONPATH=src:. python -m quant60 snapshot-decision \
  --snapshot data/snapshots/csi500-2024/manifest.json \
  --config configs/baseline.json --as-of 2024-12-31 \
  --equity 1000000 --output artifacts/csi500-2024-decision

# 默认只构建 portable momentum smoke
python tools/bundle_platforms.py

# 显式构建无 fallback 的 TargetPackage 消费器
python tools/bundle_platforms.py \
  --target-package artifacts/research-smoke/target_package.json \
  --output-dir dist/target-package
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

# Colab notebook 本地合同/执行
python tools/run_colab_notebook.py notebooks/quant_os_colab.ipynb
python tools/run_colab_notebook.py notebooks/quant_os_colab.ipynb --execute

# QMT 环境就绪后：先运行未绑定账户的只读 bootstrap（预期 exit 2），再用
# 输出的非 null broker_snapshot.json 重建同一 Signal 日 decision；
# broker observation 本身仍来自唯一下一交易日盘前窗口。完整步骤见 runbook
PYTHONPATH=src:. python tools/qmt_shadow_plan.py plan \
  --decision artifacts/latest-decision/manifest.json \
  --output artifacts/qmt-shadow-bootstrap
```

后续 `verify` 必须同时提供原始 decision，并读取 plan 时使用的既有
`QMT_ACCOUNT_HASH_KEY_FILE`；verify 不会补建丢失 key。manifest HMAC
envelope 绑定 plan/observation/snapshot 的内容与发布 byte hash、
decision/source（含 operator CLI）/policy；四个 JSON 必须保持唯一 writer
encoding。但信任主体是本地 Quant OS key holder，不是 QMT/券商。

Qlib 和真实平台的完整命令见
[`runbooks/PLATFORM_DEPLOYMENT.md`](../runbooks/PLATFORM_DEPLOYMENT.md)。

## Version and evidence policy

每个真实 run 都要记录 JoinQuant environment、QMT client/build、
`xtquant`、broker plugin、Qlib/Python、bundle hash、data version、
config/rules hash 和实际日历。文档说明 API 存在不证明当前账号有权限；
mock/fake/synthetic 成功不证明真实平台；Qlib synthetic 成功不证明模型收益。