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

创建人员：`dev.developer.ana.cai`  
文件职责：append-only 关闭 V005 唯一剩余的 package-stage/public-item 总闭包问题。  
predecessor：V005=`7534/4ce347225d5bcd35639b00b7f45dcebe3fca379b59c6b67c8bfaff4b45c1ded5`；review=`AUDIT-DEV-ANA-HIBOR-FAST-COLLECTION-DESIGN-V005=HOLD/1/1`，audit snapshot=`388384/8180a7c6af0603ec34a0f79725f3f3d7387ca3e42d3235f5827b280811049d07`。  
继承：V001–V005 已关闭的 deadline、FAST candidate/checkpoint、原子 no-replace publish/recovery、public status/manifest、quota event-family/idempotency、safe=0 pure reuse 与 6+4 性能验收全部不变。V006 仅后继替换 V002 第 6.2 节和 V005 第 2–4 节涉及的 package expected-presence/TerminalItem stop 域。

## 1. 固定符号、路径与持久化顺序

证据状态固定为 `N=物理不存在`、`V=存在且已安全 reopen/bytes/hash/schema 验证`、`I=存在且已知 partial/invalid`、`U=存在性、完整性或进程活性不确定`、`X=该 lane 不可达`。八个 package 对象固定顺序：`S=PDF staging,F=final PDF,Q=quota terminal event,A=artifact terminal event,M=manifest row,D=delivery.md,T=timing manifest,Z=persisted terminal JSON`。

顺序固定为 `Q→S/F→A→M→D→T→Z`；pure reuse 不产生 Q/A，顺序为 `existing evidence validation→S/F→M→D→T→Z`。失败不得伪造后继；只有 `P10_CLOSED` 的 closure builder 可在实际业务处理已停止后，以失败元数据写入 M/D/T/Z。`Z` 不等于 stdout：stdout public terminal 可在任何 P00–P09 停止后输出，但只有 Z 经 no-replace/reopen/hash 成功后 state 才为 P10。

`Prefix3(M,D,T)` 只允许 `NNN|VNN|VVN|VVV`，禁止 `NVN|NNV|VNV`。任一 object 为 U 时立即 `STATE_UNCERTAIN/27`，不再写后继；U 不得转换成 N/I/V。

## 2. 覆盖 V002 的权威 expected-presence matrix

### 2.1 NEW_TRIGGER lane

| state | S | F | Q | A | M | D | T | Z | 精确含义/唯一后继 |
|---|---|---|---|---|---|---|---|---|---|
| P00_INIT | N | N | N | N | N | N | N | N | preflight/scan；成功 reserve→P01，停止→stdout 或 P10 closure |
| P01_RESERVED | N | N | N | N | N | N | N | N | reservation 已 durable、尚无 quota terminal；trigger→P02 |
| P02_TRIGGER_UNKNOWN | N | N | N\|U\|V | N | N | N | N | N | `P02-N/P02-U/P02-V` 三子态见 2.3；只允许 close 或 V 后进 P03 |
| P03_CACHE_MATCHED | N | N | V | N\|U\|V | N | N | N | N | cache identity 已知；A=N 为处理中，A=V 为失败 artifact 已记，A=U fail-closed |
| P04_STAGING_PARTIAL | I | N | V | N\|U\|V | N | N | N | N | pull/写入已知 partial/invalid；只允许 recovery、failure closure 或 STOP |
| P05_STAGING_VALID | V | N | V | N\|U\|V | N | N | N | N | staging reopen/bytes/hash/PDF/page 全通过；publish 或 failure closure |
| P06_PUBLISHED | N\|V | V | V | V | N | N | N | N | final 已 no-replace/reopen/hash；manifest→P07 |
| P07_MANIFESTED | N\|V | V | V | V | V | N | N | N | manifest row 已 durable；delivery→P08 |
| P08_DELIVERY | N\|V | V | V | V | V | V | N | N | delivery 已验证；timing→P09 |
| P09_TIMING | N\|V | V | V | V | V | V | V | N | timing 已验证；terminal persist→P10 |
| P10_CLOSED | 见 2.4 | 见 2.4 | 见 2.4 | 见 2.4 | 见 2.4 | 见 2.4 | 见 2.4 | V | 仅 exact closure variant；无后继 |

### 2.2 PURE_REUSE lane

| state | S | F | Q | A | M | D | T | Z | 精确含义/唯一后继 |
|---|---|---|---|---|---|---|---|---|---|
| P00_INIT | N | N | N | N | N | N | N | N | 只读 ledger fold + 项目副本/cache identity 验证 |
| P01_RESERVED | X | X | X | X | X | X | X | X | 不可达；出现即 ContractError |
| P02_TRIGGER_UNKNOWN | X | X | X | X | X | X | X | X | 不可达；pure reuse 不打开 APP |
| P03_CACHE_MATCHED | X | X | X | X | X | X | X | X | 不可达；cache reuse 的已知 identity 不伪装 trigger stage |
| P04_STAGING_PARTIAL | X | X | X | X | X | X | X | X | 不可达；partial 不是可复用证据 |
| P05_STAGING_VALID | X | X | X | X | X | X | X | X | 不可达；验证完成后原子进入 P06 |
| P06_PUBLISHED | N\|V | V | N | N | N | N | N | N | project reuse 为 S=N；cache reuse 新 publish 为 S=N\|V |
| P07_MANIFESTED | N\|V | V | N | N | V | N | N | N | quota 三 ID 仍全 null |
| P08_DELIVERY | N\|V | V | N | N | V | V | N | N | 同上 |
| P09_TIMING | N\|V | V | N | N | V | V | V | N | 同上 |
| P10_CLOSED | 见 2.4 | 见 2.4 | N | N | 见 2.4 | 见 2.4 | 见 2.4 | V | pure closure；quota ledger bytes/hash/rows 不变 |

以上明确后继 V002 的“P06–P09 Q 必须 V”：该约束只属于 NEW_TRIGGER；PURE_REUSE 的 P06–P10 永远 Q=N、A=N、`quota_state=NONE`、三个 quota ID 全 null。

### 2.3 P02 与 A 子态

- `P02-N`：reservation 已知 durable，quota terminal 未 attempted/未 materialized；`quota_state=RESERVED`、ID=`RNN`、`trigger_attempted=true`、`triggered=null`，唯一允许 code=`PROCESS_LIVENESS_UNKNOWN|RECOVERY_UNKNOWN`。
- `P02-U`：quota terminal open/append/fsync/reopen 结果不确定；字段中不得声称 terminal event id，仍为 `RNN`，`quota_state=RESERVED`、`triggered=null`，code=`QUOTA_LEDGER_INVALID|PROCESS_LIVENESS_UNKNOWN|RECOVERY_UNKNOWN`，governance 27。
- `P02-V`：唯一 committed quota terminal 已重读验证；`RRN`，quota/trigger 只允许 `(RELEASED,false)|(CONFIRMED,true)|(UNCERTAIN,null)`。RELEASED/UNCERTAIN 只 close；CONFIRMED 或有已知 cache identity 的 UNCERTAIN 可进 P03。
- P03/P04/P05 的 `A=N` 表示 processing 仍未关闭；`A=V` 只表示 `ARTIFACT_DUPLICATE_OR_FAILED` 已 durable，ID=`RRR`，随后只可 closure；`A=U` 使 artifact ID 为 null、ID pattern=`RRN`，立即 27。P06–P09 的 A=V 只允许 `ARTIFACT_SUCCESS`。

### 2.4 P10 exact closure variants

`P10_CLOSED` 必须匹配下列且仅下列一行；`Prefix3` 使用第 1 节四个值，Z 固定 V。

| closure_variant | lane/source | S | F | Q | A | M/D/T | quota ID pattern | status domain |
|---|---|---|---|---|---|---|---|---|
| C01_NEW_SUCCESS | NEW/P06-P09 | N\|V | V | V | V-success | V/V/V | RRR | SUCCESS |
| C02_NEW_DUPLICATE | NEW/P05-P09 | N\|V | V | V | V-duplicate | V/V/V | RRR | DUPLICATE |
| C03_REUSE_SUCCESS | PURE/P06-P09 | N\|V | V | N | N | V/V/V | NNN | SUCCESS |
| C04_REUSE_DUPLICATE | PURE/P06-P09 | N\|V | V | N | N | V/V/V | NNN | DUPLICATE |
| C05_PREQUOTA_STOP | NEW-or-PURE/P00 | N | N | N | N | Prefix3 | NNN | STOPPED |
| C06_RESERVED_STOP | NEW/P01-P02-N/U | N | N | N\|U | N | Prefix3 | RNN | STOPPED |
| C07_TRIGGER_CLOSED_NO_ARTIFACT | NEW/P02-V/P03 | N | N | V | N\|U | Prefix3 | RRN | STOPPED |
| C08_PROCESSING_FAILED | NEW/P03-P05 | N\|I\|V | N | V | V-failure | Prefix3 | RRR | FAILED |
| C09_POSTPUBLISH_STOP | NEW/P06-P09 | N\|V | V | V | V-success | Prefix3 | RRR | STOPPED\|FAILED |
| C10_REUSE_POSTPUBLISH_STOP | PURE/P06-P09 | N\|V | V | N | N | Prefix3 | NNN | STOPPED\|FAILED |

补充约束：C01–C04 必须 `M/D/T=VVV`；C05–C10 可用 Prefix3，且 final=V 时 bytes/hash/page/openability 必须有效。C05–C08 final=N 时 `final_path,bytes,sha256,page_count=null`。C08 staging 的 N/I/V 取 source state：P03=N、P04=I、P05=V。C06/C07 不得伪造 artifact event；C09 的 FAILED 仅允许 manifest/delivery/timing 持久化校验失败，STOPPED 仅允许 deadline/persist/uncertain 类 code。Z 持久化失败时不进入 P10，保留来源 P00–P09 并 stdout terminal。

## 3. TerminalItem V006 封闭构造器

26 键顺序继承 V005。构造器唯一签名：

```python
def build_terminal_item(snapshot: ItemPackageSnapshot,
                        outcome: ItemOutcome) -> TerminalItem: ...
```

`ItemPackageSnapshot` 必须先通过第 2 节 lane/state/evidence validator；builder 不修复 snapshot。字段规则：

1. `state` 等于当前最高 durable package state；仅 Z=V 时为 P10。`reused_without_new_trigger=(lane==PURE_REUSE)`。
2. trigger 只允许：pre-action=`false,false`；action confirmed=`true,true`；confirmed no-trigger=`true,false`；uncertain=`true,null`。PURE 永远 `false,false`。
3. quota ID：NONE→NNN；RESERVED→RNN；RELEASED/CONFIRMED/UNCERTAIN 且 A=N/U→RRN；A=V→RRR。ID pattern 与 evidence 不符即 ContractError。
4. `final_path/bytes/sha256/page_count` 当且仅当 F=V 非空；`manifest_row_id` 当且仅当 M=V 非空；无 final 时 title/institution/date/analysts 仅保留实际已知值，禁止填造。
5. `status` 唯一判定：`code=NONE` 且 final/manifest 有效→SUCCESS；`code=DUPLICATE_EXISTING_ARTIFACT`→DUPLICATE；`code∈FAIL_CODES`→FAILED；其余非 NONE code→STOPPED。不存在 default/nearest 分支。
6. `stop_code`：SUCCESS 时 null；其余精确等于 code。`error_or_note` 只允许 `NONE|ZERO_QUOTA_REUSE|DUPLICATE_EXISTING_ARTIFACT|WARNING:TRIGGER_UNCERTAIN_CACHE_IDENTITY_CONFIRMED|STOP:<ErrorCode>|FAILED:<ErrorCode>`；不允许自由文本。“actual processing error”“high-precedence close STOP”等 V005 占位词正式删除。详细说明只可进入 top-level 脱敏 `StopReason.detail`。

`FAIL_CODES=PULL_FAILED|PDF_MAGIC_INVALID|BYTE_COUNT_MISMATCH|HASH_MISMATCH|PDF_NOT_OPENABLE|PAGE_COUNT_MISMATCH|PDF_ENCRYPTED|PUBLISH_FAILED|MANIFEST_INVALID|UNEXPECTED_EXCEPTION`。  
`STOP_CODES` 为 V003 ErrorCode 中除 `NONE|DUPLICATE_EXISTING_ARTIFACT|FAIL_CODES` 外的全部值。未知 code 拒绝。

成功细分：普通 new success=`NONE/null`；uncertain trigger 但 cache identity 已证实的 success=`stop_code=null,error_or_note=WARNING:TRIGGER_UNCERTAIN_CACHE_IDENTITY_CONFIRMED`；pure success=`stop_code=null,error_or_note=ZERO_QUOTA_REUSE`。duplicate 始终 `DUPLICATE_EXISTING_ARTIFACT`。

## 4. error code 到允许停止阶段的唯一域

令 `COMMON={DEADLINE_EXPIRED,UNEXPECTED_EXCEPTION}`；每个非 P10 item 的 code 必须属于 `COMMON ∪ STAGE_CODES[state]`：

| state | STAGE_CODES |
|---|---|
| P00 | TASK_SPEC_INVALID,CLOCK_INVALID,PROCESS_START_FAILED,PROCESS_TIMEOUT,PROCESS_OUTPUT_LIMIT,PROCESS_LIVENESS_UNKNOWN,DEVICE_NOT_UNIQUE,DEVICE_NOT_ONLINE,PACKAGE_MISSING,CACHE_UNREADABLE,ACCESS_CONTROL_PRESENT,CANDIDATE_REJECTED,LOCK_TIMEOUT,QUOTA_LEDGER_INVALID,QUOTA_REPLAY_CONFLICT,QUOTA_EXHAUSTED,QUOTA_DATE_UNCERTAIN,RECOVERY_UNKNOWN |
| P01 | PROCESS_START_FAILED,PROCESS_TIMEOUT,PROCESS_OUTPUT_LIMIT,PROCESS_LIVENESS_UNKNOWN,UI_ANCHOR_DRIFT,ACCESS_CONTROL_PRESENT,UI_CURSOR_RESTORE_FAILED,DETAIL_RESULT_MISMATCH,TRIGGER_NOT_OCCURRED,TRIGGER_UNCERTAIN,RECOVERY_UNKNOWN |
| P02 | PROCESS_LIVENESS_UNKNOWN,TRIGGER_NOT_OCCURRED,TRIGGER_UNCERTAIN,QUOTA_LEDGER_INVALID,RECOVERY_UNKNOWN |
| P03 | PROCESS_START_FAILED,PROCESS_TIMEOUT,PROCESS_OUTPUT_LIMIT,PROCESS_LIVENESS_UNKNOWN,CACHE_TIMEOUT,CACHE_AMBIGUOUS,REMOTE_FILE_CHANGED,PULL_FAILED,RECOVERY_UNKNOWN |
| P04 | PROCESS_START_FAILED,PROCESS_TIMEOUT,PROCESS_OUTPUT_LIMIT,PROCESS_LIVENESS_UNKNOWN,PULL_FAILED,BYTE_COUNT_MISMATCH,HASH_MISMATCH,RECOVERY_UNKNOWN |
| P05 | PDF_MAGIC_INVALID,BYTE_COUNT_MISMATCH,HASH_MISMATCH,PDF_NOT_OPENABLE,PAGE_COUNT_MISMATCH,PDF_ENCRYPTED,FINAL_PATH_CONFLICT,PUBLISH_FAILED,RECOVERY_UNKNOWN |
| P06 | LOCK_TIMEOUT,MANIFEST_INVALID,PERSIST_LATE |
| P07 | PERSIST_LATE |
| P08 | PERSIST_LATE |
| P09 | PERSIST_LATE |

P10 的 code 必须来自其 `source_state` 上述集合，但 source_state 只存在内部 closure input，不新增 public key；closure receipt 在 terminal package 内持久化 `closure_variant` 与 `source_state`，public TerminalItem 仍严格 26 键。一个 code 在多个 stage 可出现时，由“错误发生时最高 durable state”唯一选行，不由 code 猜 state。

## 5. 强制测试与当前 gate

1. NEW 和 PURE 两张 P00–P10 表逐格测试；X、U→N、prefix gap、pure Q/A 非 N、new P06+ Q/A 非 V 全部拒绝。
2. P02-N/U/V 三子态及 P03/P04/P05 的 A=N/U/V 全组合；每个合法组合恰好一个 quota ID pattern。
3. C01–C10 各至少一个 literal；Prefix3 四种各覆盖，非法三种均 ContractError；P10 source_state/code 交叉验证。
4. P03 cache deadline、P04 pull partial/hash mismatch、P05 publish conflict、P07 delivery persist、P08 timing persist、P09 terminal persist/crash 各做 deadline+crash/validation 反例；断言 public state、26 字段、presence、status/code/note 唯一。
5. 全 V003 ErrorCode 逐个进入且仅进入 FAIL/STOP/DUPLICATE/NONE 一类；占位/free-text/unknown code 拒绝。
6. safe_available=0：PROJECT_REUSE/CACHE_REUSE C03 成功，quota ledger bytes/hash/rows 不变；随后 NEW 在 P00 以 QUOTA_EXHAUSTED/PARTIAL_QUOTA_STOP 结束。
7. V002 recovery fault points、V004 quota family transaction、V005 16 个语义样本继续回归；V006 测试总表不得减少既有覆盖。

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