edit | blame | history | raw

慧博 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。构造器唯一签名：

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。