SHIPQ · DHF COMPLEXITY REVIEW · 2026-08-14

最复杂的 Case，不是一次写入；是一次写入失败后，仍能回到可信状态。

结论：ShipQ 中最能完整体现 DHF 的案例，是 Google Docs 内容同步的 partial-write → 受控回滚 → 独立回读 → 重新授权 → 成功续行。它同时激活 SAFE 的 S、A、F、E 四项控制。

SELECTED CASE · google_docs_content_sync controlled recovery
5精确 allowlist 文档
4最终实际变更 H1 sections
3成功写入文档；逐阶段 full readback
0未回滚写入残留
01 · SELECTION

“最复杂”指治理复杂度，不是代码行数

比较跨系统状态、授权层数、远端变更风险、证据链长度、失败恢复深度。

候选 Case跨系统授权变更风险证据 / 恢复判断
Phase 2 Google Drive packageRepo + Drivetask-scoped single-use创建远端资产receipt + readback；State Log 补记高
Level 2 smoothing Phase 0–3Registry + ledger + testsowner acceptance + phase gates主要为本地政策状态多阶段验证；无本次远端突变高
Gmail Phase 2 draftRepo + Gmail一次性确认未发送草稿partial readback；无 send中高
Google Docs partial-write recoveryRepo + policy + live Docs + version history分类、manifest、revision、逐文档 owner 确认写已生效但结构损坏receipt → freeze → restore → independent readback → new manifest最高
决定性差异：前三个 case 主要证明“能否安全开始”；这个 case 还必须证明“变更已经部分发生后，如何不扩大损害，并从真实现场恢复”。这正是 governed recovery。
02 · CONTEXT

一个内容同步，背后有四个状态世界

Repo source、动作政策、owner 即时授权、Google Docs 实时 revision 必须同时一致。

业务目标

把 Git 跟踪内容同步到既有 Google Docs，同时保护文档 ID、tab 拓扑、未映射区段与权限。

  • exact allowlist 与唯一 t.0
  • changed mapped sections only
  • 禁止 create / copy / delete / share / permission / tab topology
  • live user message only

真实事故

Canary 写入已经发生，但插入正文继承了后随段落的 H1 样式：内容存在，结构与样式错误。Writer 返回 readback_structure_mismatch。

不是“请求失败”；而是“远端已改变，但结果不合约”。
覆盖范围：下面这条时间线只显示事故恢复的关键路径，不是整个 case 的逐动作清单。发起者指“谁决定动作可以开始”；执行者指“谁实际做动作”。Owner 负责授权、回滚与继续/停止裁决；Agent 负责编排、生成、校验和本地修复；Writer / Google Docs API 负责机械执行。
PRE-MUTATION
发起：Owner 请求同步执行：Agent + manifest tool

Manifest 锁定 source、document、heading、revision 与 digest

Agent 生成只读 manifest 与 diff；Owner 对具体 digest 和 revision 确认，不是泛化许可。

CANARY WRITE
发起：Owner 明确确认 canary执行：Writer副作用：Docs API

部分写入后，结构断言失败

Writer 分阶段写入并自动回读。若内容已经写入、但结构没有达到约定，系统会保存一张永久失败回执 readback_structure_mismatch，记录实际结果，并转入冻结与恢复流程。

FAIL-CLOSED
发起：失败协议自动触发执行：Agent 停止

停止后续文档，禁止盲目重试

Agent 不继续剩余目标；失败 receipt 被保留。恢复证据不等于新写权限。

ROLLBACK
发起并执行：Owner机制：Docs 原生版本历史复核：Agent 只读回读

Owner 用 Google Docs 原生版本历史恢复

Owner 手动恢复 pre-mutation 版本；Agent 随后独立检查 content 与 styles，确认没有未回滚写入。

HARDEN + REAUTHORIZE
发起：Owner 允许继续修复执行：Agent 本地修复再授权：Owner

修复 writer，生成新 manifest，确认新 digest

Agent 修复 changed-heading selection、revision TOCTOU 与样式归一化并跑测试；HEAD 变化使旧 manifest 失效，因此必须生成新 digest，由 Owner 再次确认。

FINAL STATE
发起：Owner 接受 canary 并放行续行执行：Writer + Docs API汇总：Agent

3 个文档、4 个 H1 sections 成功；2 个零变化文档不写

Agent 逐文档编排；Writer 逐阶段读回。成功 receipt-v3 全部 readback=full；最终状态写入治理记录。

整个 case 的控制级动作清单

#动作发起者执行者关键证据 / 停点是否反复
01将动作从 Level 2 recut 为受限 Level 1，并锁定 allowlist / forbidden mutationsOwner 决策Agent 修改本地政策；Owner 记录/接受Policy digest + State Log；不等于本次写授权政策变更时才重做
02读 live revision、生成 manifest 与 diffOwner 请求同步Agent + manifest toolsource commit、document、heading、revision、digestHEAD/revision 变化即重做
03确认 canary 的 manifest digest 与 revisionAgent 展示确认项Owner 明确确认per-document confirmation每份文档 / 每个新 manifest
04按 stage 写入 skeleton / table insert / fill / style已消费的 Owner 授权Writer + Google Docs API每 stage 带 requiredRevisionId每个 stage 重复
05每 stage 后 fresh readback 与结构断言Writer 自动触发Writer / Docs read APIstage receipt；revision、内容、结构、样式每个 stage 重复
06Canary mismatch 后冻结后续写入Failure protocolAgent / writer fail-closed失败 receipt；禁止 blind retry本案实际发生 1 次
07恢复 pre-mutation 原生版本Owner 裁决Owner 在 Docs UI 执行version history + restored revision本案实际发生 1 次
08独立验证恢复后的 content / stylesAgent 提起只读复核独立 readback 路径content_restored=true、styles_restored=true回滚后必须执行
09本地修复 writer 并加回归测试Owner 允许继续Agentselection、TOCTOU、paragraph style commits/tests直到本地门禁通过
10新 manifest、新 digest、新 revision 再授权Agent 生成并展示Owner 确认旧确认不能复用发生 HEAD/revision 漂移就循环
11成功 canary、Owner UI 接受、再处理其余有变化文档Owner 放行继续Agent 编排；Writer/API 执行per-stage receipt v3 + owner acceptance按文档重复；零变化则跳过
12最终全目标回读、receipt 汇总与治理记录Agent 收口；Owner 为治理责任人Agent + read API3 written / 2 no-write / 0 unrolled write终局一次；失败则回相应停点

流程中确实存在反复，但不是无条件重试

ACTUAL LOOP · 实际发生

事故恢复循环 × 1

Canary write → structure mismatch → freeze → Owner rollback → independent readback → writer fix → new manifest → new authorization → canary retry。

ACTUAL FEEDBACK · 实际发生

验证器归一化反馈

后续结构检查曾因 table 顺序和 hard-wrap 段落分组假设报错；归一化合法表示后重新读回，才确认真实结构正确。验证器本身也必须被验证。

DESIGNED LOOP · 正常重复

Stage × Document 双循环

每个有变化文档都按多个 write stage 执行；每个 stage 后 fresh revision/readback。Canary 先行，Owner 接受后才进入其余文档。

CONDITIONAL LOOP · 本次终局未触发

Revision drift 循环

若检查后、写入前 revision 已变化：拒绝写入 → 重新生成 manifest → Owner 重新确认。仓库证明此门禁存在，但没有证据显示最终成功执行触发过该分支。

03 · DHF ROUTE

DHF 如何路由这个 case

风险出现后，路线从“实现”切到“冻结—恢复—再验证”，有新事实与授权后才返回执行。

01 RECOVER恢复现场State Log、HEAD、policy、revision
02 GOVERN分类与边界原 L2；recut 为受限 L1
03 SPECIFYManifest目标、diff、digest、revision
04 AUTHORIZE逐次确认live message + per-document
05 EXECUTE分阶段写入revision lock + fresh readback
06 VALIDATE结构不匹配preserve receipt · stop
07 ROLLBACK原生恢复Owner 控制
08 FACT CHECK独立回读content + styles + topology
09 FIX最小修复selection · TOCTOU · style
10 RE-GATEFresh evidencetests + new HEAD + digest
11 REAUTHORIZE新确认旧确认随 digest 失效
12 HANDOFF可信完成receipt v3 + State Log
Recover → Govern → Specify → Authorize → Execute → Validate ⇢ Rollback → Re-validate → Re-authorize → Complete
04 · SAFE CORE

SAFE 是每次状态变化的控制内核

S 定义完成，A 决定推进权，F 证明现场，E 保证可恢复。

S

Specification

把“同步文档”收窄成可判定动作。

  • 5 个 allowlist 文档，唯一 t.0
  • Git tracked source only
  • changed sections only
  • 结构、文本、样式、tab 进入 DoD
A

Authorization

授权绑定具体动作快照。

  • Level 2 默认 deny；后受限 recut
  • live user message only
  • digest + owner-confirmed revision
  • 重试必须重新确认
F

Facts

用现场证据替代“应该成功”。

  • source commit 与 digest
  • pre/post revision 与 receipt v3
  • 逐阶段 fresh readback
  • 独立 semantic / native verification
E

Error-recovery

失败是受控状态迁移。

  • unknown / mismatch 分离
  • 保留 receipt，禁止 blind retry
  • native version-history restore
  • rollback 后重验与 handoff
关键时刻SAFE推进条件
写入前范围与 DoD确认 manifest + revisionHEAD / digest / revision预定义 rollback四者同时成立
结构失败断言指出违约旧授权不覆盖重试mismatch receipt停止、保全证据不得继续
回滚后恢复 pre-mutationOwner 执行恢复独立 content + styles readback确认无残留只证明已恢复
再次执行新 writer + manifest重确认 digest / revision新测试与 receipt v3failure protocol 保持不复用历史 green
05 · RECOVER

RECOVER：失败或结果不确定后的七个处理阶段

SAFE 判断在哪里停；RECOVER 规定停下后如何恢复事实、状态与重新推进的资格。

R1

Recognize

Recognize the partial or uncertain outcome：识别已经发生或无法确认的副作用。

E1

End

End further mutation：立即停止后续写入。

C

Capture

Capture the failed receipt and scope：保留失败回执和影响范围。

O

Obtain

Obtain the last trusted state：取得最后一个可信状态。

V

Verify

Verify restoration independently：独立验证 content 与 styles 已恢复。

E2

Escalate

Escalate for fresh authority：提交新 HEAD、manifest、digest 与 revision，取得新授权。

R2

Resume

Resume only from proven state：只从已证明状态恢复执行。

边界：RECOVER 恢复事实和连续性，不自动授予 connector 重试、发布、生产写入或破坏性动作权限。
06 · STATE MODEL

失败之后不能直接回到 Execute

安全属性是每个失败态都有唯一、可审计、不扩大影响面的出路。

PREPARED
manifest ready
AUTHORIZED
revision bound
MUTATED
remote changed
MISMATCH
structure bad
FROZEN
retry denied
RESTORED
native version
VERIFIED
independent readback
禁止边：MISMATCH ─X→ RETRY　／　RESTORED ─X→ EXECUTE（没有新 manifest 与新 owner confirmation）
Governed 恢复：恢复本身也受契约、授权和证据约束。它把 mutated-but-untrusted 转成 restored-and-verified；随后仍要重新授权，才能再次产生副作用。
07 · BUSINESS VALUE

SAFE 控制如何转化为 TRUST 业务价值

这个案例覆盖 TRUST 五域；价值来自可信状态变化，不是更多流程。

T · TRUST & QUALITY诚实区分状态

“结构错”“已恢复”“成功”是不同事实。

R · RISK CONTROL限制影响面

Canary 失败立即停止，避免缺陷扩散。

U · UNIT PRODUCTIVITY避免重复劳动

只写变更区段，不碰零变化文档，也不盲目重试。

S · SERVICE CONTINUITY缩短恢复路径

预绑 revision 与 rollback，失败后无需猜测。

T · TRACEABILITY AT SCALE控制可复用

Manifest、receipt v3、failure protocol 沉淀为可审计门禁。

08 · EVIDENCE

证据来源与声明边界

此页只读解释，不触发任何远端动作。

仓库证据锚点
  • docs/designs/harness-state.md:1242–1274：staged execution、最终 scope、receipt-v3、rollback 终态。
  • docs/requirements/google-docs-content-sync-policy-v2.json：allowlist、trigger、write / failure protocol。
  • docs/plans/2026-08-04-gdocs-sync-style-fix-and-resume-plan.md：根因、错误分类、停止与回滚。
  • scripts/google_docs_sync_write.py 与 tests：mismatch、revision guard、receipt persistence。
  • Commits 0c7ca95、4871257、35e1245、2951965：hardening 与最终记录。
边界：历史证据不证明今天仍有 connector 权限，也不授权重跑。当前 ShipQ repo 为 clean main，HEAD 162b7af；新远端写入仍需重查授权、revision 与目标状态。