edit | blame | history | raw

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

创建人员：dev.developer.ana.cai
文件职责：append-only 关闭 V008 的 budget 分类、file/liveness 分离和 public wire 版本化三项。
predecessor：V008=5781/1ecfd31ec959781cef17c31fdecee9f73b5d9f0af2fb41a9f7013de725cbf2df；review=AUDIT-DEV-ANA-HIBOR-FAST-COLLECTION-DESIGN-V008=HOLD/3/3，audit snapshot=404357/4f42b9caa19f415e50c6c78e49250de58953edc725f688df0b391f193f06a0d7。
继承：V008 TerminalReceipt 的 N/I/U/V 方向、V007 U 不进入 P10、V006 package/TerminalItem 总矩阵及 V001–V005 已关闭合同均不变。本版精确替换 V008 第 1–3 节的 T00/T03 与 public top-level schema。

1. 已知预算耗尽与事实未知严格分离

close_budget_remaining_ms<=0 是由 monotonic deadline 算出的已知事实，不是 U。若 Z writer 尚未调用：

  • receipt：persist_attempted=false,persisted=false,presence=N,operation_completed=false,liveness_unknown=false；
  • public：status=TIME_BUDGET_STOP,capability_status=TIME_BUDGET_STOP,exit_code=10,stop_code=DEADLINE_EXPIRED；
  • item state 保留 source_state，Z=N，stdout 发出预算终态；不得写 Z。

只有 S/F/Q/A/M/D/T 的事实或执行进程活性不可确定时才为 STATE_UNCERTAIN/27。pre-Z U 同样不调用 Z，但其 code 必须是精确 uncertainty code，不能借用 DEADLINE_EXPIRED。

2. TerminalReceipt V009：文件事实与执行活性正交

12 键顺序继续为：

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

V008 的 N/I/V 规则不变；U 精确分成两行：

outcome attempted persisted presence operation_completed liveness_unknown error_code 含义
T03F_FILE_FACT_UNKNOWN true null U true false RECOVERY_UNKNOWN writer 调用已确定返回/退出，但 close/reopen/file-id/bytes/hash 无法唯一判定
T03L_WRITER_LIVENESS_UNKNOWN true null U null true PROCESS_LIVENESS_UNKNOWN writer 是否退出不确定，禁止 observer/readback

因此 presence=U 不再强制 liveness_unknown=true。U 的合法 cross-field 仅为上述二选一；operation_completed=false,presence=U、operation_completed=true,liveness_unknown=true、operation_completed=null,liveness_unknown=false 均 ContractError。两行均保留 source P00–P09、Z=U、P10 predicate=0、后继 writer=0、public STATE_UNCERTAIN/27。

3. 七个且仅七个 Z outcome

id 场景 receipt 核心 public status/exit state/Z
T00U pre-Z object U false/false/N/false/false STATE_UNCERTAIN/27 source/N
T00B 已知 close budget 耗尽 false/false/N/false/false TIME_BUDGET_STOP/10 source/N
T01 CreateNew/open 已知失败且 target absent true/false/N/true/false STOP from PERSIST_LATE source/N
T02 terminal 已知 partial/invalid true/false/I/true/false STOP from PERSIST_LATE source/I
T03F writer 已结束，file facts unknown true/null/U/true/false STATE_UNCERTAIN/27 source/U
T03L writer liveness unknown true/null/U/null/true STATE_UNCERTAIN/27 source/U
T04 terminal valid true/true/V/true/false inherited outcome P10/V

T00U 与 T00B receipt shape 相同，但由 error_code 唯一区分：T00U=PROCESS_LIVENESS_UNKNOWN|RECOVERY_UNKNOWN|QUOTA_LEDGER_INVALID，T00B=DEADLINE_EXPIRED。不存在按最接近映射。

4. report_collection_terminal V009（固定 51 键）

schema_version='HIBOR_FAST_REPORT_COLLECTION_TERMINAL_V009'；message_type='report_collection_terminal'；contract_version='REPORT-COLLECTION-CAPABILITY-V1'。

前 43 键逐字、逐序、逐类型继承 V003/V004，形成兼容前缀：

schema_version,message_type,contract_version,project_id,task_id,handoff_id,source_role_instance_id,source_thread_id,target_role_instance_id,target_thread_id,reply_thread_id,requester,review_owner,run_id,mode,status,capability_status,exit_code,stop_code,blocker,observed_at_utc,started_at_utc,ended_at_utc,total_elapsed_ms,work_deadline_reached,close_deadline_reached,requested,triggered,succeeded,failed,duplicates,gaps,quota_confirmed,quota_uncertain,quota_active,quota_cumulative_consumed,quota_safe_available,quota_ledger_path,items,manifest_path,delivery_path,timing_path,prohibited_action_attestation

只在该 43-key prefix 之后 append 8 键：

terminal_target_path,terminal_path,terminal_presence,terminal_present,terminal_persist_attempted,terminal_persisted,terminal_operation_completed,terminal_liveness_unknown

类型/交叉约束：

  • terminal_target_path=Path；terminal_path=Path|null；terminal_presence=N|I|U|V；terminal_present=BOOL；terminal_persist_attempted=BOOL；terminal_persisted=BOOL|null；terminal_operation_completed=BOOL|null；terminal_liveness_unknown=BOOL。
  • 八个 suffix 值逐字段等于 TerminalReceipt 对应值；terminal_present=(presence==V)，terminal_path 仅 V 非空。
  • schema key count/order/extra/missing 先验证；V003 strict 43-key 消费者不得把 V009 当 V003。兼容规则为“前 43 键名称、顺序、类型和语义不变 + additive suffix”；消费者按 schema_version 选择解析器。
  • project_legacy_v003(record) 是唯一兼容投影：只删除末尾 8 键并把 schema_version 改为 HIBOR_FAST_REPORT_COLLECTION_TERMINAL_V003，其余 42 值 byte-semantic 相同。CLI 默认只输出 V009；仅显式 --terminal-schema V003 才输出投影，同一次 run 不双写、不双发。
  • V003 投影仍通过 status/capability_status/exit_code/stop_code 表达 T00B 与 T00U/T03F/T03L，不声称 terminal presence；V009 是 package review 的权威 schema。

5. 强制测试

  1. T00B close-budget=0：receipt N/no-attempt，public TIME_BUDGET_STOP/10，绝不出现 STATE_UNCERTAIN。
  2. T00U 分别用 pre-Q/pre-A/pre-M U：receipt N/no-attempt，public 27；与 T00B exact predicate count=1。
  3. T03F：模拟 writer 已返回但 reopen/file-id unknown；断言 completed=true/liveness=false/U/27。T03L：模拟 writer 未确认退出；断言 completed=null/liveness=true/U/27、observer=0。
  4. 七个 outcome 做所有 bool/null 交叉负例；每个合法对象唯一匹配一行。
  5. V009 51-key literal：键序、类型、missing/extra、receipt equality；前 43 名称序列与 V003 完全相等。
  6. 显式 legacy 投影恰为 43 键；除 schema_version 外，其余 42 值与 V009 prefix 相同。默认执行只生成一个 V009 stdout/persist target。
  7. V001–V008 所有回归不减少；仍强制 P10=>所有 evidence known 且 Z=V。

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