fix: enforce canonical factor contract json (#15)

README.md

@@ -19,6 +19,7 @@
 ## 模块
 
 - `alpha_factors` — 158 alpha 公式 + 24 基础算子（移植自 qlib alpha158）
+- `factor_contracts` — `FactorDefinition` / `FactorSetRef` v1 纯计算合同、严格 PIT/availability 输入准入与显式 legacy 投影
 - `execution` — A 股长仓执行仿真（成本/滑点/现金约束）+ 稀疏调仓/完整交易日 Ledger + 可投影成交与 NAV 审计；T+1、涨跌停、成交量与价差提供独立约束函数
 - `indicators` — 50+ 技术指标（MACD / KDJ / 布林 / ATR / ADX / 等）
 - `data_adapter` — 桥接 qtdb_pro 长表与新模块（rename / long-wide / 复权 / vwap 代理）
@@ -195,6 +196,51 @@ print(backtest.stats())
 print(backtest.benchmark_report())
 ```
 
+## 因子／特征合同 v1
+
+`quant_engine.factor_contracts` 提供 `researchhub.factor-definition` 与
+`researchhub.factor-set-ref` `1.0.0`。合同使用受限 canonical JSON：只接受 ASCII
+lower-snake-case object key、UTF-8 string、bool/null 和 safe integer；小数参数必须用显式
+canonical decimal string。定义、输入映射、上游证据、输出 schema/content 和 lineage 的任一
+语义变化都会产生新 identity。
+
+创建 `FactorSetRef` 必须提供完整且可重算 identity 的 `DatasetSnapshotEnvelope` 与
+`DataFoundationEnvelope`，不能用 ID 字符串或布尔值代替资格证明。每个因子输入都要映射到一个
+实际选中的 `StandardizedViewRef`，schema 必须同时匹配定义和 view；未消费、缺失、重复或跨
+snapshot/Foundation/PIT 的 view 都会失败关闭。snapshot PIT 可以早于 Foundation/view PIT，
+但始终满足 knowledge ≤ snapshot PIT ≤ Foundation/view/FactorSet PIT ≤ evaluation。
+
+```python
+from quant_engine.factor_contracts import (
+    DataFoundationEnvelope,
+    DatasetSnapshotEnvelope,
+    FactorDefinition,
+    FactorSetRef,
+)
+
+snapshot = DatasetSnapshotEnvelope.from_dict(dataset_snapshot_v1)
+foundation = DataFoundationEnvelope.from_dict(data_foundation_v1)
+
+# definition 必须是完整的 FactorDefinition；FactorSetRef.create 还要求显式 input bindings、
+# view availability、output quality/coverage、canonical output bytes 和 immutable artifact ref。
+factor_set = FactorSetRef.create(
+    definitions=(definition,),
+    dataset_snapshot=snapshot,
+    foundation=foundation,
+    **explicit_factor_set_evidence,
+)
+```
+
+`availability_mode="as_available"` 声明 source/view 和计算产物在历史 evaluation 前实际可用；
+`"retrospective_replay"` 保留历史 evaluation，但要求真实 publication/view creation、compute 和
+artifact 时间位于之后，并固定 `historical_availability="not_established"`。两种模式都不会授予
+decision、real-data、production、paper 或 live readiness。
+
+旧 `governed_pipeline.FactorVersion` 的四字段构造器、`factor_id@version`、run/target/risk/order
+identity 均保持不变。迁移只能通过 content-addressed `LegacyFactorBinding`，再显式调用
+`bind_legacy_factor()` 或 `project_legacy_factor()`；后者是有损投影，不表示旧 digest 与新定义
+digest 等价，也不会把旧 run 静默升级为新合同。
+
 ## 治理垂直切片
 
 `governed_pipeline` 不复制因子、回测、组合或执行算法，只编排现有能力并补充版本与风险契约。