ADR-0202：显式、可重放的 Compose 恢复证据收集

状态：Accepted
日期：2026-07-29
关联 RFC：QL-RFC-0001 D-175、D-190、D-191、D-192
关联 ADR：ADR-0185、ADR-0200、ADR-0201

背景

ADR-0200/0201 将 rollout backup 与 restore safeguard 作为不可变恢复证据保留，并分别设置 8/4 份目录上限。该策略避免了自动恢复和无界增长，但如果没有受审的空间回收入口，低闪存路由器最终只能停止升级或恢复。

直接删除 .sqlite 也不安全。旧 compose-apply 和 compose-restore-commit 的精确回放会重新检查原快照；文件消失后，调用方无法区分“已经受审收集”与“意外丢失”，甚至可能把响应丢失误判为需要再次启动或恢复。收集过程还可能在 rename、tombstone、commit receipt 或 unlink 之间崩溃。

决策

1. 收集是显式、短生命周期的两阶段操作

既有 ql3-local-deploy 增加：

compose-evidence-collect-prepare
compose-evidence-collect-commit

命令只接受当前 UID 私有的 exact command file，不接受通配符、目录、任意路径、自动年龄阈值或调用方提供的 snapshot digest。prepare 显式列出 rollout/restore UUID，只验证候选、当前 generation、Profile、保留底线和 immutable receipt/snapshot 绑定，并发布 collection lock 与 prepare receipt；它不删除或移动任何大文件。

commit 必须使用同一 collection ID/generation，且时间不早于 prepare。

2. Profile 固定保留底线和单次预算

Edge：每次最多收集 1 个文件；至少保留 2 个 rollout backup、1 个 restore safeguard。
Standalone：每次最多收集 4 个文件；至少保留 4 个 rollout backup、2 个 restore safeguard。

每一类只能选择按 durable receipt recordedAtMs + UUID 排序后的最老前缀，不能跳过旧证据先删较新的恢复点。某一类没有收集候选时，不要求部署人为制造该类最低数量。restore safeguard 只有存在 terminal commit receipt 时才是候选。

这些底线不是自动 retention policy。系统没有 timer、watcher 或磁盘水位触发器；达到 8/4 上限时仍由 operator 明确审查并执行。

3. Tombstone 保持旧命令的精确回放语义

每个已收集大文件对应一个小型、append-only、0600 tombstone，绑定：

artifact kind 与 UUID；
collection ID、generation、Profile 和 commit 时间；
原 rollout/restore terminal receipt 的 SHA-256；
SQLite contract、SHA-256、bytes、page count 和 page size。

旧 apply/restore 回放在大文件存在时继续检查物理 snapshot；文件不存在时只接受与当前不可变 source receipt 和原 snapshot facts 全部匹配的 tombstone。否则失败关闭。restore 回放明确返回 source|safeguard=collected，并保持 service.state=unchanged；collection 不获得 Docker authority。

Tombstone 和 prepare/commit receipt 体积有硬上限，但当前版本不自动压缩或删除 tombstone 历史。它解决大 SQLite 文件的闪存占用，不宣称元数据永远有界；后续若需要压缩，必须有独立的摘要归档协议。

4. Commit 使用 rename → tombstone → receipt → unlink

每个 snapshot 在原目录被 rename 到确定性的 .ql3-collection-stage，复验完整 SQLite evidence 后发布 tombstone。全部 tombstone durable 后发布 collection commit receipt，最后 unlink stage 并删除 collection lock。

原命令重放必须覆盖：

final 已 rename、tombstone 尚未发布；
tombstone 已发布、commit receipt 尚未发布；
commit receipt 已发布、stage 或 lock 尚未清理；
response 已丢失但 durable commit 已完成。

收集前后都验证 source receipt digest。final/stage 冲突、receipt/tombstone 漂移、 generation 变化、权限异常或未完成的其他 operation 都失败关闭。

5. 与 revision、rollout、restore 双向围栏

collection prepare 在发布自己的 lock 前后检查 revision、rollout 和 restore lock。 revision/apply/restore 在 mutation 前检查 collection lock，并在发布自身 lock 后再次检查。竞争中只能有一方保留 durable authority；失败方在任何 image、Docker 或 SQLite mutation 前释放自己的新 lock。

6. 不新增 package 和常驻成本

实现位于现有 @qinglong/local-owner-cli/local-deployment 的 package 内部目录，复用 @qinglong/local-sqlite/rollout-safety 检查 snapshot。没有新增 workspace package、第三方生产依赖、daemon、端口、listener、timer 或 watcher。该选择也落实 ADR-0185：小能力优先用包内 subpath 表达，只有独立交付/权限/依赖边界才拆 package。

验收证据

local-owner-cli 48/48，通过现有部署、rollout、restore 与新增 collection 回归；
专项覆盖 Edge 最老前缀、保留底线、rename 后崩溃恢复、commit 精确重放、 collection/revision 围栏；
rollout backup 收集后，旧 apply 只读 tombstone 并且不产生新的 Compose up；
restore safeguard 收集后，旧 restore commit 返回 safeguard=collected, service.state=unchanged；
TypeScript build 通过，workspace 仍为 22 个 package且没有新增生产依赖。

真实断电、闪存 wear/写放大和长周期 tombstone 压缩仍是独立门禁。

2026-08-01 补充：SQLite write contract 已推进到 v42。Tombstone v1 的 snapshot contract 不能固定为创建本 ADR 时的 v40，否则当前证据不可收集；也不能只改成 v42，否则升级前的 v40/v41 证据无法回放。当前 reader 接受受审历史窗 40..42，最大值由已经合法持有 local-sqlite/rollout-safety authority 的 apply/collection/restore 调用方显式传入；evidence 模块自身不新增 storage import，未来版本仍默认拒绝。v42 部署专项 23/23、local image audit 7/7、19-package 全量门和 dependency boundary 均通过。

被拒绝的替代方案

按 mtime 自动删除：mtime 不是恢复 authority，且会引入后台资源和竞态。
删除 receipt 与 snapshot：破坏精确回放和审计链。
只留下“已删除”布尔值：不能绑定原文件内容和 source receipt。
先 unlink 再写 tombstone：进程崩溃会把受审收集变成不可区分的数据丢失。
另建 backup/GC package 或 daemon：没有独立交付边界，并增加低配节点安装和 idle 成本。

6.4 KiB Raw Permalink Blame History Unescape Escape