CC-Switch/docs/pi-support-restructure-zh.md

# 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. 工作方式反转:测试先行

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

1. **Claude 先交付认证级测试套件**:把 R1–R4 审出的全部故障场景 + 契约义务固化为可执行测试(含扫描器负向 fixture);测试即契约的字面;
2. **Codex 实现到全绿**:不得修改认证测试(发现测试本身有错时,报告并由 Claude 裁决修订);可以自由增补自己的测试;
3. 全绿 + 内部自审(修正案 2 §F 对应节)后进入该前置工程的盲审;
4. 盲审 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 不触碰。