feat: add Quant OS A-share baseline

docs/ARCHITECTURE.md

@@ -0,0 +1,274 @@
+# Quant OS architecture and trust boundaries
+
+Quant OS 是项目；`quant60` 是第一版 A 股 Baseline 内核、CLI namespace
+和 artifact 协议前缀。当前形态是模块化单体：共享可移植计算和稳定合同，但把
+数据供应商、hosted 平台、QMT 专有运行时与券商事实放在不同信任边界内。
+
+```text
+JQData (authorized account)
+  get_bars(raw OHLCV/money, factor, pre_close, limits, paused)
+  + daily PIT is_st + daily PIT index membership
+                    |
+                    v
+       canonical immutable snapshot
+       exact-set/hash + semantic reconstruction
+                    |
+          +---------+----------+
+          |                    |
+          v                    v
+ snapshot-backtest      snapshot-decision
+ local event engine     Signal -> Target -> Order Delta
+          |                    |
+          +---------+----------+
+                    |
+            portable-momentum-v1
+                    |
+       +------------+-------------+
+       |            |             |
+ JoinQuant bundle  QMT bundle   local contract oracle
+ hosted backtest   built-in/qmttools backtest-only
+
+synthetic PIT/features -> purged walk-forward -> Ridge challenger
+                                                  (not deployment-frozen)
+
+Qlib 0.9.7:
+  native portable-momentum signal bridge
+  Alpha158 + LightGBM + Recorder research workflow
+  (no L3 target / L4 order-intent parity)
+
+XtTrader:
+  read-only broker observation -> HMAC account-bound shadow plan
+  callback/mutation boundary remains uncertified and operator-inaccessible
+```
+
+箭头表示数据或合同流，不表示平台能力等价。hosted 引擎拥有自己的时钟、行情
+和成交语义；broker snapshot/callback 才是现金、持仓、可卖量、订单和成交的
+事实权威。本地 ledger 不能用预测持仓覆盖券商事实。
+
+## Runtime split
+
+| Layer | Runtime | Rule |
+| --- | --- | --- |
+| Quant OS / `quant60` | Python ≥3.10 | 本地回测、snapshot pipeline、research、ledger、CLI |
+| JQData ingestion | 独立 Python 环境，`jqdatasdk==1.9.8` | 只从授权账户获取数据；凭据不进入快照 |
+| Qlib research | CPython 3.12.x，`pyqlib==0.9.7` | 与本地/QMT 环境隔离；provider 必须授权且版本化 |
+| Portable strategy core | Python 3.6-compatible source | 无第三方依赖；bundler 内联到 hosted 策略 |
+| JoinQuant hosted | 平台管理 | 上传生成的单文件；不能假设安装本地包 |
+| QMT built-in | QMT Python 3.6 | 只上传 bundle；模块全局 `g` 持久状态，避免 `ContextInfo` 用户属性回滚 |
+| qmttools / XtTrader | 券商分发的 native Python | `xtquant` 专有且 lazy import，不进入仓库 |
+| Colab | notebook runtime | 默认只跑无账号流程；JQData/Qlib 是显式可选 cell |
+
+不要用一个 Python 环境强行兼容所有路径。
+
+## Data plane and point-in-time semantics
+
+JQData adapter 的输入合同是逐交易日历史指数成员和 `get_bars` 日线字段：
+
+- 未复权 `open/high/low/close`、`volume`、`money`；
+- 复权因子 `factor`；
+- `pre_close`、`high_limit`、`low_limit`、`paused`；
+- 每个 member-date 的严格布尔 PIT `is_st`；
+- `skip_paused=False`，保留停牌日语义。
+
+快照保存 `bars.jsonl`、`memberships.jsonl`、`quality.json` 和
+`manifest.json`。发布期间存在 incomplete marker；完成后 verifier 要求目录
+是精确 artifact 集、每个文件 hash 正确，并从 JSONL 重建领域对象，重算质量
+汇总、内容 hash 和 `data_version`。这比“下载成功”更强，但在授权真实账户运行
+并保存许可/lineage 前，仍不构成 G1 证据。
+
+JQData 日线在 24:00 完成，因此 adapter 拒绝把 Asia/Shanghai retrieval
+当日作为 `T_CLOSE_COMPLETE`；请求 `end` 必须早于抓取日期。字段、ST 或成员
+覆盖不完整也不会被当成默认 false/空集合。
+
+`snapshot-decision` 只用 `as_of` 当日精确 PIT 成员和截至当日的数据。
+执行/名义价格保持 raw；动量把每个历史 close 乘以当日可见 factor，再归一到
+决策日因子，因此后续公司行动不会改写已经形成的历史决策。held but
+untradable 标的不会从 Universe 消失，而会进入 frozen / hold-only /
+sell-only 状态。
+
+若目标用于下一交易日开盘前 shadow，Signal 时钟仍是 T 日 15:00。snapshot
+冻结 JQData `get_trade_days` 与 `get_all_trade_days` 一致性校验后的完整
+交易日序列，并显式保存 end 日后的唯一 `next_trading_session`。decision、
+broker snapshot 和 shadow plan 必须绑定同一个相邻 session，以及
+Asia/Shanghai `[09:00,09:30)` 的 `first_executable_window`；elapsed-day
+阈值和 weekday 近似都不是权威。周末、T 日 15:01、错过 09:30、错误 session 或
+迟到多日全部 fail closed，国庆等长假只要下一 session 来自冻结日历即可。
+
+账户绑定后还必须保持决策规模有效。shadow 对 `decision.equity` 和当前
+`total_asset` 使用固定的
+`max(1 元, 0.01% × abs(decision equity))` 包含边界容差；缺失、负数、
+非有限值或超差都不能进入 ready，超差原因码为
+`DECISION_EQUITY_DRIFT`。该合同进入 plan hash，verifier 会从原始两个权益值
+重新计算差额、阈值和 blocker。
+
+QMT shadow verifier 使用 semantic replay，而不把 plan 当成事实来源。
+`broker_observation.json` 保存 query 后 adapter state、live flag、callback
+error/live-authorization history 计数、query 起止、原始记录数、校验结果及
+脱敏资产/持仓/委托/成交事实。原始 decision manifest 是 verify 的必需输入。
+纯 replay 从这两个输入独立重建 account binding、clock gate、资产和现金
+恒等式、open/order-stability、trade/fill identity、完整 blocker 集、
+snapshot-valid、完整 broker snapshot、逐 symbol target/weight/lot、
+board-lot/sellable feasible delta、proposal、portfolio 和 status，再与 plan
+exact compare。因而 plan 中同步改写多个派生字段或删除 blocker 不能形成新的
+`SHADOW_READY`；READY 也强制存在可重建 snapshot。
+
+普通 artifact hash 之外，planner 使用既有 account HMAC key 和独立 domain
+签署 `QMT_SHADOW_EVIDENCE_V1` envelope。envelope 绑定完整 plan、
+broker observation、broker snapshot 的 canonical 内容 hash 和三份实际发布
+bytes 的 SHA-256、原始 decision manifest hash、planner/engine 及 operator
+entrypoint `tools/qmt_shadow_plan.py` source hash，以及 semantic version、
+10 秒/1 元 policy ceiling 和 equity drift policy。四个发布 JSON（包括
+不参与自签名的 manifest）还必须逐 byte 符合唯一 deterministic writer
+encoding。verifier 从当前真实输入与磁盘实际 bytes 重建
+envelope 并 constant-time 比较 MAC；缺失、错误或轮换后的 key 全部失败。
+这提供的是 Quant OS 本地 evidence publisher authenticity/完整性，不是
+QMT/券商对 query result 的原生签名，也不把 adapter 升级成 broker-certified。
+
+策略安全阈值是 canonical policy：query window 上限 10 秒，资产/持仓市值和
+`cash + market_value = total_asset` 的绝对容差上限 1 元。CLI 只能使用等于
+或更严格的值，builder 与 replay 都拒绝更宽值。目标权重总和还必须不超过
+1，作为无报价条件下可独立证明的决策现金预算；实时 buying power（含成交价、
+费用和卖出先后）仍不作证明。
+
+持仓 drift 不会复用旧持仓：每次 target diff 都从当前券商 positions 和
+sellable quantity 重算，且 open/变化中订单会阻断。因此数量 residual 不会
+因旧持仓静默失真。由于 shadow 没有实时执行价，现金购买力仍不能被证明；
+plan 明示该限制，ready 仅供人工审阅，不能升级为 live submission。
+`trade.amount` 当前会被标准化、认证和重放，但在缺少真实
+terminal/xtquant build 探针时不假设它与 `price × quantity` 的精确误差
+合同；它不参与 target diff，正式券商验收必须记录 build 并冻结字段容差。
+
+`snapshot-backtest` 在每个历史决策日重新调用同一 decision path，并使用：
+
+- 第一实际交易日完整收盘形成计划；
+- 紧接着下一实际交易日开盘尝试成交；
+- 当日供应商停牌/涨跌停/前收字段；
+- 上一交易日成交量参与率；
+- T+1、百股交易单位、显式费用和未成交撤销。
+
+这是本地 fill model，不是 JoinQuant 或 QMT 的成交事实。
+
+## Research and model boundary
+
+synthetic research pipeline 已实现：
+
+- PIT table 和未来值拒绝；
+- Universe 原因码；
+- 透明价量特征与 T+1-open 标签时钟；
+- train-only winsor/impute/standardize；
+- purge/embargo walk-forward；
+- deterministic Ridge、OOS IC/RankIC；
+- factor risk、dated cost/capacity 和 constrained target。
+
+这些功能证明研究管线可执行。Ridge 尚未冻结成带版本、输入 schema 和推理
+hash 的 deployment bundle，也没有授权真实长样本 OOS 与四引擎推理验证，因此
+不是生产 champion。
+
+Qlib 路径固定为 `0.9.7`。CPython 3.12 实际 fixture smoke 已得到：
+
+- native momentum：24 条 signal；
+- Alpha158 + LightGBM：完成 fit、SignalRecord、SigAnaRecord、
+  PortAnaRecord 和 model 保存；
+- 两条 workflow 都保存表级 hash、行列/时间边界和从 portfolio report
+  重算的有限值指标，明确 `investment_value_claim=false`；
+- local MLflow file store 使用时，runner 以
+  `os.environ.setdefault("MLFLOW_ALLOW_FILE_STORE", "true")` 显式确认。
+
+该 fixture 只有两只股票和一个 benchmark，性能没有投资意义。Qlib 的单一
+`limit_threshold` 也不能表达逐日板块/ST 规则，所以它只参与 L1/L2 和诊断
+L6，不声称 L3 target 或 L4 order-intent parity。
+
+## Portable strategy and platform boundary
+
+当前可跨 hosted wrapper 冻结的共同基线是 `portable-momentum-v1`。平台 API
+不得进入 symbol normalization、momentum score、target weight、target
+quantity 和 order delta 计算。
+
+canonical 股票代码采用 JoinQuant 形式：
+
+| Canonical | QMT/XtQuant | Qlib |
+| --- | --- | --- |
+| `600000.XSHG` | `600000.SH` | `SH600000` |
+| `000001.XSHE` | `000001.SZ` | `SZ000001` |
+| `830799.XBSE` | `830799.BJ` | `BJ830799` |
+
+转换权威是 `quant60.portable_core.normalize_symbol`。当前 XtTrader mutation
+边界只接受 `.SH` / `.SZ`，不能从转换覆盖推导北交所实盘覆盖。
+
+QMT built-in bundle 和 qmttools runner 都硬限制为 backtest/history。built-in
+状态存放在模块全局 `g`，不写入可能在下个 `handlebar` 回滚的
+`ContextInfo` 用户属性。两条路径固定中证 500 benchmark、PIT 历史成分/ST
+与 baseline 费率；built-in 的 10% 参与率由 QMT GUI 设置，qmttools
+程序化传入。live mutation 只存在于外部 XtTrader adapter，并且默认关闭、
+未认证、没有 live 启动命令；operator 可运行的 shadow CLI 只接受查询边界。
+
+## Stable artifacts and release integrity
+
+最低交换合同是：
+
+- [`signal.schema.json`](../schemas/signal.schema.json)；
+- [`target.schema.json`](../schemas/target.schema.json)；
+- [`order_event.schema.json`](../schemas/order_event.schema.json)；
+- [`broker_snapshot.schema.json`](../schemas/broker_snapshot.schema.json)。
+
+`verify-manifest` 不仅检查 ledger hash chain，还检查 incomplete marker、
+精确 artifact 集、SHA-256、ledger head、report/manifest identity、
+saved/current source aggregate、saved/current schema aggregate 和 payload
+schema。`verify-snapshot-decision` 与 data snapshot semantic verifier 承担
+各自边界的同类职责。
+
+这些合同已有自动测试；最近一次标准库套件为 211 tests、OK、3 个可选路径
+skip。测试结果不能替代 schema 迁移演练、真实平台导出或券商回调认证。
+
+## Clocks and reconciliation
+
+canonical weekly clock 是：
+
+```text
+ISO 周第一实际交易日：完整 close
+  -> 使用 as_of 之前实际可得信息形成 signal/target/order intent
+紧接着下一实际交易日：open executable window
+  -> 刷新市场规则与 broker snapshot
+  -> pre-trade gate
+  -> backtest/shadow submit 或 fail closed
+  -> callback append + reconciliation
+```
+
+“紧接着下一日”是交易日关系，不是固定星期几。每个真实平台 run 必须记录
+`signal_as_of`、`last_feature_bar`、`first_executable_time`、
+price adjustment 和 fill model。
+
+完整 reconciliation 要同时比较 cash、positions、sellable quantities、
+open orders 和带时区的新鲜 `as_of/source_time`。legacy/partial snapshot
+即使数值碰巧平衡，也不能把 `safe_to_open` 设为 true。
+
+## Facts and current claim
+
+| Fact | Authority |
+| --- | --- |
+| canonical symbol、portable calculation | versioned source + config |
+| snapshot 内容 | semantic verifier 通过的 immutable snapshot + manifest |
+| historical provider entitlement | 实际数据账户许可与保存的 lineage 记录 |
+| hosted 回测时钟/成交 | 平台真实导出 |
+| cash、position、order、fill | broker snapshot/callback |
+| 程序化交易权限与报告 | 实际券商书面确认 |
+| Gate 状态 | [`gate_scorecard.json`](../gate_scorecard.json) |
+
+synthetic/fake 数据是合同测试，不是市场证据；Qlib synthetic fixture 的真实
+运行是运行时证据，不是收益证据；mock parity exporter 是 wrapper 合同证据，
+不计 G9。
+
+## Remaining production gaps
+
+当前还缺：
+
+- 授权 JQData 真实快照、基本面公告 PIT、完整公司行动/Security Master；
+- Ridge/LightGBM 冻结模型包和真实 OOS 证据；
+- 真实数据校准的风险、冲击、容量和 TCA；
+- 真实 JoinQuant/QMT 导出；
+- 券商状态映射、restart recovery daemon、20 日 shadow 与连续对账；
+- 运维监控、kill-switch 演练和程序化交易合规确认。
+
+所以 Quant OS 是可执行、可继续填证据的生产候选框架，不是已经达到整体
+60 分的实盘系统。证据政策见
+[`AUDIT_2026-07-25.md`](AUDIT_2026-07-25.md)。