# 慧博 10 分钟快速采集工具开发方案 V008

创建人员：`dev.developer.ana.cai`  
文件职责：append-only 关闭 V007 唯一 terminal Z 自身不确定性矛盾。  
predecessor：V007=`4389/2637a549332248739db71740d143683cc476576644af340ecc22b599aa4e8376`；review=`AUDIT-DEV-ANA-HIBOR-FAST-COLLECTION-DESIGN-V007=HOLD/1/1`，audit snapshot=`398084/b65e2d16042cd11d89d3a2d2f848ada8c99519a05cddc226c3098a699a729a06`。  
继承：V007 对 pre-Z U 的全部约束、V006 package/TerminalItem/ErrorCode 总矩阵及 V001–V005 已关闭合同不变。V008 仅替换 V003 `TerminalReceipt` 和 V007 第 1–2 节中 Z 自身的 receipt/presence 表达。

## 1. TerminalReceipt V008 固定 schema

字段顺序固定 12 键：

`target_path,terminal_path,persist_attempted,persisted,presence,operation_completed,liveness_unknown,stdout_emitted,bytes,sha256,error_code,source_state`

类型与枚举：`target_path=Path`；`terminal_path=Path|null`；`persist_attempted=BOOL`；`persisted=BOOL|null`；`presence=N|I|U|V`；`operation_completed=BOOL|null`；`liveness_unknown=BOOL`；`stdout_emitted=BOOL`；`bytes=int|null`；`sha256=Hash|null`；`error_code=ErrorCode|null`；`source_state=P00_INIT..P09_TIMING`。`source_state` 是 Z 尝试前最高 durable state；receipt 不改变该事实。

固定交叉约束：

1. `persist_attempted=false` 时仅允许 `persisted=false,presence=N,operation_completed=false,liveness_unknown=false,terminal_path/bytes/sha256=null`。
2. `presence=V` 当且仅当 `persist_attempted=true,persisted=true,operation_completed=true,liveness_unknown=false,terminal_path=target_path,bytes>=2,sha256!=null,error_code=null`；仅此行将 public item state 置 P10。
3. `presence=I` 表示已安全观察为 partial/invalid；固定 `persist_attempted=true,persisted=false,operation_completed=true,liveness_unknown=false,terminal_path=null,error_code=PERSIST_LATE`。若 bytes/hash 均安全取得则二者非空；否则二者同时 null，不允许只知其一。
4. `presence=U` 当且仅当 `persist_attempted=true,persisted=null,operation_completed=null,liveness_unknown=true,terminal_path/bytes/sha256=null,error_code=PROCESS_LIVENESS_UNKNOWN|RECOVERY_UNKNOWN`。U 不得降级 N/I/V。
5. `presence=N,persist_attempted=true` 表示 CreateNew/open 已知失败且 reopen 证明不存在；固定 `persisted=false,operation_completed=true,liveness_unknown=false,terminal_path/bytes/sha256=null,error_code=PERSIST_LATE`。
6. `stdout_emitted` 记录实际事实；正常 parent 仍存活时 T00–T04 固定 true。若输出通道本身不确定，则 terminal delivery 为外层 `DELIVERY_AMBIGUOUS_NO_RETRY`，不回写本 receipt、不重发。

## 2. 五个且仅五个 Z outcome

| id | 场景 | attempted | persisted | presence | operation_completed | liveness_unknown | state | Z evidence | 后继 |
|---|---|---:|---:|---|---:|---:|---|---|---|
| T00 | pre-Z 任一 S/F/Q/A/M/D/T=U 或 close budget 不足，未调用 writer | false | false | N | false | false | source_state | N | stdout 27；结束 |
| T01 | Z CreateNew/open 已知失败且确认 target absent | true | false | N | true | false | source_state | N | stdout STOP；结束 |
| T02 | Z 已知 partial/invalid | true | false | I | true | false | source_state | I | stdout STOP；保留原件；结束 |
| T03 | Z write/flush/fsync/close/reopen/hash 或 writer liveness 不确定 | true | null | U | null | true | source_state | U | stdout 27；保留未知；结束 |
| T04 | Z no-replace/write/flush/fsync/close/reopen/hash 全通过 | true | true | V | true | false | P10_CLOSED | V | stdout normal terminal；结束 |

T00 的 pre-Z U 仍按 V007：不得尝试 Z。T03 是 V007 未覆盖的新边界：writer 已被调用，所以绝不允许 `persist_attempted=false` 或 Z=N。T01/T02/T03 均不得进入任一 P10 closure；只有 T04 先验证 V006 C01–C10 的 known-input predicate，再进入 P10。

## 3. Public/package 一致性

- T00/T01/T02/T03 的 `TerminalItem.state=source_state`；top-level `terminal_path=null,terminal_present=false`。新增 top-level `terminal_presence=N|I|U|V` 与 receipt presence 相等；`terminal_present` 仍是 BOOL，只在 V 时 true。
- T03 top-level `terminal_presence=U,terminal_present=false,terminal_persist_attempted=true,terminal_persisted=null,liveness_unknown=true`；public capability 固定 STATE_UNCERTAIN/27。
- T02 `terminal_presence=I,terminal_present=false,terminal_persisted=false`；不得把 partial target 当正式 terminal。
- T04 `terminal_presence=V,terminal_present=true,terminal_persisted=true`，path/bytes/hash 与 receipt 完全相等。
- manifest/delivery/timing 和 quota 字段不因 Z outcome 改写；失败后禁止 delete/truncate/overwrite/rename/backfill/retry。

## 4. 强制故障注入

1. pre-writer、CreateNew、每个 write chunk、flush、fsync、close、reopen、bytes/hash 各一点；每点断言唯一 T00–T04、12 键 schema 与 state。
2. CreateNew 后可安全 reopen partial→T02；无法确认 writer 退出/目标事实→T03；两者不得按 T01。
3. T03 断言 attempted=true、persisted=null、presence=U、operation_completed=null、liveness_unknown=true、P10 predicate call count=0、后继 writer=0。
4. T00 断言 attempted=false；分别注入 Q=U、A=U、M/D/T=U 与 close budget 0，证明与 T03 可区分。
5. 将 T03 任一字段伪装为 attempted=false/persisted=false/presence=N 或 T04 含 U，均 ContractError。
6. T04 必须通过 no-replace、strict JSON、bytes/hash/reopen；否则只能 T01/T02/T03，不得宣称 P10。

当前状态：`PENDING_INDEPENDENT_DESIGN_REREVIEW`。V008 PASS 前不创建候选源码/测试/quota ledger，不运行 Python/ADB/APP/dry-run，不触发下载；新增 trigger=`0`。