# v0.40 多策略跨币种独立前向目标观察

入口 `/research/portfolio-forward`，也可在归档历史的多策略完整包上点击“创建组合观察”。支持 v0.38 多策略组合的 1–6 项策略和 2–8 个币种；本版不把 v0.37 C07 等权/逆波动组合作为独立观察模型。

## 冻结与审核

从当前工作区已保存且可校验下载的多策略完整归档冻结：币种集合、单一交易所、日线、成本、风险上限、策略预算、原研究规则哈希和归档身份。新版本为 candidate，需管理员/所有者以至少 5 字理由审核配置到 validation，再启用到 shadow；可随时暂停。暂停候选版本不能绕过首次审核，重新启用建立新 epoch 并清空该期上下文，旧期证据保留。

历史归档收益仍为客户端计算。关联归档只提供配置与历史文件追溯，不把收益排名、归档文件或配置审核等同于策略验证通过。没有 approved 状态和生产准入；观察覆盖率不授权交易。

## 模型与时间语义

原 C01/C02/C03/C04/C06 具有固定 ATR 保护与持仓状态，不能单用当日 entry 条件代替。首次新收盘为每币截取 290 根完整日线，前 260 根预热，从统一固定历史起点按冻结 v0.38 基准成本回放到当前收盘；读取期末清仓前的虚拟数量和保护状态。随后只追加每币一根新日线，历史回放起点不滚动。没有传入未来或虚构 K 线，历史回放净值不计为前向收益。

在已确认收盘时，持仓模型份额且无收盘退出的策略继续提出激活目标；空仓模型份额需收盘 entry、有限 ATR，且以收盘价×(1+滑点)估计的保护价为正，才提出激活目标。原五策略按该份预算的 40%，C07 按原波动率目标，先逐币比例限额，再按总仓统一缩放。输出策略×币种目标矩阵和目标现金；历史数量/费用只用于模型状态连续性，不作为账户仓位或前向业绩展示。

这是收盘时的**理论次期开盘目标**，不是原 v0.38 下一根成交的承诺：下一期开盘跳空、实际入场保护可行性、仓位漂移和 2 个百分点调仓阈值，在收盘时尚不能解析，故不把目标看成已执行权重。理论最早应用边界等于收盘边界，实际采集晚于此边界，不声称可按开盘价成交。原 v0.38 完整历史报告、终端清仓和研究包哈希保持不变；新增只读收盘状态捕获接口。

只有启用后的最新 UTC 日线收盘可记录；收盘后 60 秒确认，10 分钟内计为按时。北京时间对应每日 08:00 收盘边界，采样不早于 08:01。所有币种必须到达同一当前边界，采集时间距写入小于 2 分钟，原始行情哈希须匹配，禁止交易所自动切换、用户传入价格或历史时钟。若采集跨越 UTC 日线边界，整次失败并等待新边界重试。

同一版本/期/收盘只记录一次，原子写入全部币种的组合目标；任一行情失败不保存部分目标。重叠历史修订或缺少前次收盘校验会阻止追加。漏采不会补录，重新截取 290 根历史，显式记录 gapBars/reset 并以现金初始建议重建本次上下文，前次目标仍留在旧记录中。

## 证据与复算

每条包含冻结定义哈希、观察期、应收盘/实际记录时间、按时标记、缺口、首次/重置完整预热、其余日期新增各币日线、源地址/采集时间/快照哈希、完整上下文哈希、历史模型状态哈希、前后目标。仅保留计算用的历史上下文，来源全量请求的快照哈希是采集收据；离线复算不证明交易所真实性。

完整证据导出跨全部观察期，含完整审核链并附内容 SHA-256。项目安装依赖后可执行：

```sh
node --experimental-strip-types scripts/reproduce-portfolio-forward.mts --file portfolio-evidence.json --out replay.json
```

输入最多 6 MiB，输出路径必须不存在。先验证审核、期次、时间、来源、预热和目标链，再逐次从保存的历史重新跑组合模型，要求目标及模型状态哈希完全一致。重新计算外层哈希不能使篡改目标通过数值复算。零条观察只代表空结构可读，不是已有前向证据。

## 权限、接口与运行器

所有者/管理员审核启停；研究员可创建和手动采样；查看者可读取及导出。独立 API 密钥使用 research:read / research:observe，不能管理版本。原基础与 C07/M03 观察路由隔离新模型，不会误读或采样。

| 方法 | console 路径 | 范围 |
| --- | --- | --- |
| GET | `/api/console/research/portfolio-forward` | 当前工作区版本投影 |
| GET | `/api/console/research/portfolio-forward/detail?id=UUID&before=0` | 审核链、覆盖和每页 50 条观察 |
| POST | `/api/console/research/portfolio-forward` | `{id,archiveId}`，冻结配置 |
| POST | `/api/console/research/portfolio-forward/state` | `{id,revision,state,note}` |
| POST | `/api/console/research/portfolio-forward/observe` | `{id}`，手动一次 |
| POST | `/api/console/research/portfolio-forward/export` | `{id}`，完整证据 |

GET `/api/v1/research/portfolio-forward` 及其 `/detail`，和空对象 POST `/api/v1/research/portfolio-forward/tick` 提供独立密钥通道；console 也可 tick。观察/导出各自最多每工作区 6 次/分钟。每个版本/期/目标收盘的一次采样尝试计一个手动评估或计划扫描单位，失败重试不重复计量；不会按币种重复计量。角色、客户会话和资产启用在异步采集后原子复查，暂停/移除权限阻止提交。

```sh
python3 public/integration/trendlab-shadow-runner.py --env-file PRIVATE_ENV --lane portfolio --once
```

保持 trendlab-runner.py 同目录，凭证和私有站点认证沿用原规则。去掉 --once 才启动常驻循环；baseline/advanced 默认行为兼容。页面发布不会创建定时任务、观察版本、启用采样或真实消息/交易。

## 容量、恢复与回退

共享每工作区 50 个生命周期版本、5000 条观察；每组合最多 4 MiB 证据、1.5 MiB 当前状态、600 根/币种连续历史。达到上限停止新增，不截断。连续历史达到 600 根可导出、暂停并开始新一期；证据上限跨期累计，需在共享容量允许时创建新版本，重新启用不会释放旧证据容量。数据库备份总量仍限 8 MiB，多个大版本需管理员原生备份。

无新表或迁移，保留 44 张业务表与 20 个迁移。新模型 `portfolio-forward-targets-v1` 进入发布/回退清单；不支持该模型的 v0.39 不能直接回退，即使数据库结构相同。

当前便携恢复工具为二十一文件，在 v0.39 十八文件基础上增加 portfolio-forward-contract.mjs、portfolio-forward-rules-v040.json、portfolio-forward-recovery.mjs。旧十八文件逐字节冻结于 `/integration/v039/`。恢复检查配置、归档引用、审核、各期上下文及目标结构链，暂停组合观察；完整数值重算由上述 CLI 执行。归档索引仍标记为待补传，不把数据库备份当作 R2 文件备份。

验证证据见 `verification-v040.json`。合成和隔离接口测试不等于真实持续运行：本轮没有启用生产组合观察或部署常驻主机，未做浏览器点击验收或收集真实前向收益。

后续优先建设组合滚动训练/测试验证、目标观察与真实纸面执行的独立对账，再根据证据决定准入；实际前向业绩与交易执行需单独开发和验收。