qinglong/docs/adr/ADR-0490-run-history-terminal-preservation.md

ADR-0490：Run History 终态保全与跨领域完成证明

• 状态：Accepted（D-396 实现、本地完整门禁与远程 37-job CI 已通过）
• 日期：2026-08-23
• 决策：D-396
• 关联：ADR-0482、ADR-0483、ADR-0484、ADR-0485、ADR-0488、ADR-0489

背景

QingLong 2.x 的 CrontabStats、Logs 与 QingLong 3.0 的 Runs、RunAttempts、RunEvents、StepRuns 等对象都属于运行历史，但两代模型并不具备可证明的一一映射。把旧统计或日志行直接插入 3.0 Run ledger 会伪造 Run identity、event sequence、Attempt/Step 关系与执行来源；用 target 覆盖 Legacy 又会违反 append-only 历史边界。

D-391 因而把 Run History 全部标为 blocked，D-394 completion 也只能拒绝该领域。这个保守默认能避免数据损坏，却使一个已经停稳、只要求保留两侧历史的迁移永远不能形成完成证明。D-396 必须提供真正可完成、但不冒充历史转换的领域 adapter。

决策

1. Run History adapter 是保全证明，不是数据导入器

Legacy 与 target 的历史继续保存在 ADR-0482 已封存的 capture bundle 中。adapter 不执行 INSERT、UPDATE、DELETE、checkpoint、日志复制、格式转换或外部上传，也不把旧行回灌到 3.0 Run ledger。

合法裁决固定为：

• Legacy Run History 的每个 required fact 必须选择 retain_both / preserve_both；
• Target Run History 的每个 required fact 必须选择 retain_target / preserve_target；
• adopt_legacy、exclude_legacy、defer、manual_external 或任意 blocked fact 都不能形成保全证明。

receipt 只绑定 bundle、review、application、领域 inventory 与 fact counts，不保存表名、Run ID、状态值、日志、路径或 row body。

2. 只有确定终态的 target history 可被提升为 required

Legacy capture 已由 stopped source fence 固定，因此其 Run History 可进入 historical_preservation_required。Target 必须从 exact sealed SQLite 重新证明：

• Runs 存在 status 与 finished_at_ms，所有 Run 只能是 succeeded|failed|cancelled|timed_out，且具备完成时间；
• 若存在 RunAttempts，不能有 claimed|starting|running Attempt；
• 若存在 StepRuns，所有 Step 只能是 succeeded|failed|skipped|cancelled|timed_out，且具备完成时间；
• 缺少 canonical 列、active/waiting/retry/lost Run、active Attempt、pending/waiting/running/lost Step 或查询漂移继续保持 blocked / historical_integrity_required。

该判断同时用于 diagnostics、review commit 和 adapter replay；operator 不能通过修改私有 decision file 把 active Run 提升为可保全。

3. 新增独立短生命周期 preserve/verify 命令

既有 ql3-local-deploy 增加：

local.deployment.reconciliation.run-history.preserve
local.deployment.reconciliation.run-history.verify

preserve 重新打开 sealed application、plan、bundle 与 owner-private decision file，重放全部 canonical facts，并要求 review authorization 的 decision file digest/count 完全一致。它只允许 Run History domain 为 adapter_required，并绑定 exact reconciliation_application_planned 或 reconciliation_automation_applied source head。

每个 preservation directory 最多只含 receipt.json，以 no-replace publication、file/directory fsync 和 exact replay 收敛，最终文件/目录权限为 0400/0500；catalog 上限 64。receipt 发布或封存后的 response loss 可由相同命令继续完成，不覆盖冲突证据。

preserve 不增加 instance head 状态。它本身不授予 restart；若在发布期间另一个 adapter 推进 head，该证明会因 source-head digest 脱离而不能被 completion 消费，调用方必须在新的终态 head 上使用新 preservation ID 重新证明。这避免了多个独立 adapter 状态的组合爆炸。

4. Completion schema v2 消费第二种 adapter evidence

completion command/receipt 保留 v1 兼容语义；只有携带 Run History preservation 时使用 schema v2。固定八领域证据新增：

run_history + adapter_required + run_history_preservation

completion 重新验证 sealed preservation、原 decision stream、bundle fingerprint、application plan 与 source head；调用方只能提交 preservation ID 和 expected digest，不能自报 domain evidence。adapterCount 从 0|1 扩展为 0|1|2，允许 Automation apply 与 Run History preservation 同时作为已证明 adapter。

完成时间不得早于 application commit、Automation apply 或 history preservation 中任一最新证据。v1 receipt 仍按原规则读取和验证；v2 receipt 必须实际包含 Run History preservation，不能用版本号绕过领域证明。

5. 低资源与集群边界

实现内聚于既有 @qinglong/local-owner-cli/src/deployment/reconciliation/application/run-history/，不新增 workspace package、production dependency、binary、daemon、timer、watcher、listener、socket、SQL migration 或 src/ 根平铺。

Edge/Standalone 每次最多打开一个 sealed SQLite handle，状态判定均为 LIMIT 1，decision file 继续使用 64 KiB 流式缓冲；长期新增资产只有一个小型 content-free receipt，不复制数据库或日志。

本 ADR 只定义 Local SQLite 保全。Cluster/PostgreSQL 的 Run History 必须使用数据库 snapshot、事务一致性、租约/运行收敛与 HA retention 的独立证明，不能复用本机路径或把 Local capture bundle 当成集群历史 authority。

被拒绝的替代方案

把 Legacy 统计和日志导入 3.0 Run ledger

拒绝。没有 Run/Attempt/Event/Step identity 与顺序证明，导入会制造看似完整但语义虚假的运行记录。

只保存 source database 的 SHA-256

拒绝。整库 hash 会被其他 adapter 对无关表的合法写入破坏，也不能表达签名的 append-only 保留选择。D-396 绑定 sealed bundle 与 Run History domain inventory。

每增加一个 adapter 就新增 instance head 状态

拒绝。八领域会产生顺序与组合爆炸。无 DML 的 history proof 绑定当前 source head，最终由跨领域 completion 一次 CAS。

把 active/lost Run 当成历史

拒绝。running|waiting_approval|retry_wait|lost 都可能仍需执行、恢复或人工裁决，封存为完成历史会丢失运行 authority。

验收条件

1. terminal Legacy/Target history 从 blocked 精确提升为 required；active/inconclusive target history 始终 blocked。
2. 只有 legacy retain_both + target retain_target 的完整 signed canonical decision stream 可发布 receipt。
3. receipt 不包含名称、路径、Run ID、状态值、日志或 row body，且收敛为 0400/0500。
4. receipt publication/seal response loss exact replay；替换、篡改、额外 catalog、stale head 与 decision drift 全部失败关闭。
5. completion v2 重新验证 preservation 并生成固定八领域 evidence；completion v1 保持兼容。
6. preserve/verify 无 SQLite DML、数据库复制、service、Docker、network 或后台对象。
7. 聚焦、完整 Local Owner、tracked backend、18-package、package/dependency/source boundary、artifact/Edge import 与远程 CI 全部通过后，本 ADR 才能转为 Accepted。

当前证据

• 聚焦 Run History：2/2，覆盖终态 preserve/verify、两处 response-loss replay、v2 completion、CLI content-free、active Run blocked、人工越权拒绝与 sealed receipt 篡改。
• 既有 completion v1 聚焦回归：2/2。
• 完整 reconciliation：48 total / 46 pass / 2 conditional Docker skip / 0 fail；完整 Local Owner：273 / 266 / 7 / 0。
• tracked backend：D-396 实现提交为 1561 total / 1559 pass / 2 conditional skip / 0 fail；最终远程修复提交增加一项 rollout-generation 合同测试后为 1562 / 1560 / 2 / 0。18-package clean build/test 为 2919 / 2897 / 22 / 0。
• package/dependency/source boundary、service-manager bridge import、Edge import 与十四档 Local artifact audit 全部 compatible；workspace 仍为 18 packages、singleSourcePackages=[]、shallowSourcePackages=[]，Local Owner 为 175 source / 174 nested / 1 root binary entry。
• 基础 Edge/Standalone 制品保持 2,611,978 / 2,612,056 bytes、319 files、58 loaded modules；本阶段未把一次性 Owner authority 带入常驻小设备 runtime。
• D-396 实现提交 42262094 在远程暴露了两个与 Run History 领域逻辑无关、但会削弱总门稳定性的既存 live-test 时序问题：PostgreSQL claim takeover 只把过期时间置于数据库时钟前 1 ms，以及 Provider 证据在滚动发布后保存任意 Ready Pod 快照。
• 85e244f6 仅把测试夹具中的 claim 置于完整 30 秒租约之外，未改变生产租约语义；6001174e 让 Provider 发布和每次瞬态证据重试都重新绑定 exact qinglong.io/provider-generation 的非终止 Ready Pod，并继续保留 UID/restartCount/requestCount 与 CIDR 断言。
• 最终远程 QingLong 3.0 CI 为 37/37 success；此前失败的 PostgreSQL 16 arm64、其余 PostgreSQL 16/18 x64/arm64 矩阵及 Provider K3s + CloudNativePG material/CIDR rotation/failover gate 全部通过。独立 Kubernetes deployment live contract 同样通过，因此本 ADR 转为 Accepted。