Pi 支持项目级重启裁决:前置工程结构与测试先行

文档状态:项目级裁决(用户 2026-08-01 批准),优先级高于既有契约、修正案 1/2 的交付与审查结构条款;契约的技术条款(不变量、类型、义务)继续有效。触发:R4 未通过,三个 invariant 家族第四次出现,按修正案 2 §G 项目级硬停止。裁决依据:四轮证据表明问题不再是契约缺失或未落实(R4 时 oracle 已真实、类型屏障已就位),而是认证单元过大(12k 行 × 高不变量密度 × 零 High 标准 = 每轮必有新 High)与实现方稳定的"九成对一成微妙错"率共同作用。修复对象是认证结构与工作方式,不是再写一份修正案。

1. 新结构:三个前置工程 + 主工程,认证单元 ≠ PR 数量

单体累积认证(检查点 A/B/C)废止。改为:

工程	范围	认证对象	预算
前置 A	Provider 类型化写面 + endpoint 所有权(全 app)	`dao/provider_write.rs`、相关 service 入口、扫描器及其测试	2–3 轮
前置 B	Data-only canonical restore(含 R4 新发现:safety backup 并发丢写窗口、binary TOCTOU、incremental auto-vacuum 保留)	`database/backup.rs`、`schema.rs` 的 restore 面及测试	2–3 轮
前置 C	只读 native inspection(完全由 pinned Pi 语义向量驱动)	`pi_config/raw_schema.rs`、`composer.rs`、`native.rs`、`gateway.rs`(capability 部分)、oracle 夹具及测试	2–3 轮
主工程	Skills/Prompts/Sessions/UI/i18n + gateway 数据面	建立在已认证前置之上,认证结构届时另定	另计

每个前置工程是独立认证对象:两位 fresh blind reviewer 审该组件的完整文件与测试(组件级审计,不是 diff 审计),小到一轮看得透;
依据 handoff §2.2"双盲审数量不等于 PR 数量"与规则 8/9"同一 invariant 重复失败 → 重审 boundary 与 test strategy":重构认证结构正是执行该规则,各前置工程作为新认证对象持有独立小预算,这不是绕过七轮纪律,而是其结论;
最终交付仍是一个 PR(用户要求不变);前置工程在同一分支上以 commit 组推进;
任一前置工程在自己的预算内不收敛 → 单独停止上报,不牵连其他工程。

2. 工作方式反转:测试先行

四轮共同病根之一是实现方的字面合规:契约文字与测试之间的任何缝隙都会变成缺陷。自本裁决起:

Claude 先交付认证级测试套件:把 R1–R4 审出的全部故障场景 + 契约义务固化为可执行测试(含扫描器负向 fixture);测试即契约的字面;
Codex 实现到全绿:不得修改认证测试(发现测试本身有错时,报告并由 Claude 裁决修订);可以自由增补自己的测试;
全绿 + 内部自审(修正案 2 §F 对应节)后进入该前置工程的盲审;
盲审 finding 若揭示测试套件的缺口,缺口先补进测试,再修实现——测试套件是活的认证资产,逐工程滚动加厚。

3. R4 finding 的归属(全部并入对应前置工程的测试范围)

Finding	归属
managed DTO 把 thinkingLevelMap 收窄为 `Option<String>`,oracle 证明必须无损	前置 C
gateway 把 Authorization/x-api-key/x-goog-api-key 列为 protected 并强制 apiKey,header-auth 配置误降 DirectOnly	前置 C
restore 行校验只查 storage class/JSON/decimal,`sort_index=-1` 可发布后生产读取失败	前置 B
safety backup 与 publish 之间并发丢写窗口;binary restore TOCTOU;canonical stage 丢 incremental auto-vacuum	前置 B
`update_provider_settings_config` 绕过类型化写面且零行静默成功	前置 A
`reconcile_provider_record` 先查存在再分支,并发 create 冲突退化为覆盖更新	前置 A

结构教训一并纳入:DML allowlist 必须缩到 provider_write.rs 模块级(R4 逃逸正是因为按文件豁免了整个旧 DAO);"252/252 字段执行过"不等于下游语义正确,前置 C 必须有 oracle→managed→inspection 的端到端无损往返测试。

4. 盲审材料与验证(每个前置工程)

材料:该组件的规范契约节选(中立重生成)、组件文件清单、oracle/provenance(前置 C)、验证命令、通用审查维度;不含任何轮次历史、finding、自审报告;
验证:cargo fmt --all -- --check、cargo clippy --lib --tests -- -D warnings(必须带 --tests,认证模块是 #[cfg(test)],不带就不编译它)、cargo test --lib 全套 + 组件认证测试全绿 + 扫描器负向 fixture 红名单确认,均在干净 SHA 上;
完成条件:零 validated blocker/high/data-integrity finding。

文档考据说明:修正案 1/2(pi-support-contracts-amendment-*.md)的条款已按其自身要求合并进 pi-support-contracts-zh.md 与 pi-support-review-contract-zh.md,独立文件已随合并删除,这是预期状态而非丢失;本文引用的"修正案 2 §F/E1"以合并后的规范文档对应章节为准。

4.6 前置 B 终止关账(用户裁决,2026-08-02,优先于 §4.5)

§4.5 的缩围执行后,重认证 R1 仍在存量产品面出现 3 项 High(配置目录可变性竞态、restore 未复用写面校验链、safety backup 可预测文件名)。用户裁决: PR 聚焦 Pi 业务,restore 老面放一放,不乱扩张。据此前置 B 终止关账:

Pi 耦合面已达成且在两套认证套件中持续全绿,Pi 工程期间完成的加固随 PR 保留;
5 项未决 finding 与 v1–v15 历史导入移交 docs/restore-hardening-debt-zh.md (独立"Restore 加固工程"债务登记),不在本 PR 范围;
infra 基线(schema.rs/migration.rs/backup.rs)已在前置 A 套件中按 3fa6b1f1 状态重冻:本 PR 内任何再触碰即认证红,机械防止范围回潮;
前置 B 不再有重认证轮次;§4.5 的 N/N−1 缩围作为已落地事实保留。

4.5 范围修订(用户批准,2026-08-02)

前置 B 的不可信恢复(SQL/binary 双入口)缩围为仅接受 user_version N 与 N−1 (当前 16/17):迁移语义 invariant 家族四次复发均位于历史迁移链,其对抗深度与 "导入远古备份"的产品价值长尾严重不匹配。v1–v15 输入结构化拒绝;本地升级链 v1→17 完全不受影响(LocalUpgrade 就地迁移照旧);升级前备份(N−1)回滚路径保留并专测。v1–v15 恢复立项为"历史备份导入"独立未来工程,已建成的 MigrationSourceSpec 架构留作其地基。

5. 冻结事实(2026-08-01)

分支 feat/pi-native-support,HEAD = 10f2dacb(R4 检查点),工作树干净;
R1–R4 已耗于已废止的单体认证;前置工程各持新的 2–3 轮预算;
未 push、无 PR;stash@{0}、legacy/pi-041ff113、PR #5598 不触碰。

6.6 KiB Raw Blame History Unescape Escape