qinglong/docs/adr/ADR-0072-unified-local-execution-completion-and-control-lifecycle.md

ADR-0072：统一的本机执行完成、取消、超时与停机生命周期

• 状态：Proposed
• 日期：2026-07-20
• 关联：D-18、D-21、D-65、D-67 至 D-70、ADR-0005、ADR-0007、ADR-0066、ADR-0068 至 ADR-0071

ADR-0087 现行增量：本文 control lifecycle 已迁入 @qinglong/local-execution/control；/recovery 可单向消费其 completion processor，其他 subpath 不得反向导入 control/recovery。

上下文

ADR-0068 至 ADR-0071 已分别建立启动恢复、持久化进程、原子启动协调和有界调度，但完成 Promise、启动恢复回执、取消、Attempt deadline、回执清理和应用停止仍可能由不同 lifecycle 推进。若每条路径各自实现终态映射或拥有 timer，会产生迟到成功覆盖取消、同一 Attempt 重复完成、停机后孤儿进程，以及低配路由器空闲唤醒和内存状态随任务数增长的问题。

决策

1. 新增独立 Profile-neutral 控制包

新增 @qinglong/local-execution-control。生产只依赖 @qinglong/runtime-core 与 @qinglong/local-process，不得导入 SQLite adapter、Profile importer、legacy、cluster、ORM 或 HTTP。依赖方向固定为：

runtime-core <- local-process <- local-execution-control <- local-run-recovery
                                            ^
                                            |
                                   local-application

local-run-recovery 与在线 lifecycle 共享同一个 LocalCompletionReceiptProcessor；Run/Attempt 的成功、失败、取消和超时终态只能由该处理器或同包内的控制协调器提交，不再保留两套回执认证和终态事务实现。

2. 完成回执是唯一正常完成事实

dispatcher 不向 application stack 返回进程 completion Promise。它只在 Promise settle 后向组合根发送 Attempt ID；通知采用最多 64 个 identity 的进程内合并集合，不携带 token、exit code、命令或日志内容，也不是耐久事实。通知丢失时，周期性数据库候选与启动恢复仍能收敛。

处理器先从唯一 RunRepository 重读 Attempt/Run，再读取 exact receipt，并校验 Run ID、Attempt ID、callback sequence、token digest 和时间边界。可信回执在一个 Repository transaction 中按 Attempt Event、Run Event 顺序 CAS 终态；终态提交后才删除 receipt 并解除 journal。已终态 Attempt 的同一或下一 callback sequence 回执只做认证和清理，不得改写终态。非法回执必须先保存 quarantine intent，再移动文件。

3. deadline 先转为 durable cancellation intent

SQLite source 只使用已有 cancellation/deadline 索引，以 (dueAtMs, kind, attemptId) 稳定 keyset 返回最多 64 条候选。deadline 到期后，协调器先 CAS 写入 cancelRequestedAtMs、cancelReason=timeout 与 run.cancel_requested，随后才能停止进程；数据库失败不得 signal。

所有取消先尝试消费可信 completion。仍 active 时，只能把最新 runtime-owned local-process Attempt 的完整 durable handle 交给 LocalProcessController；禁止裸 PID signal。claimed 可直接终结，starting/running 只有 exact stop 返回 stopped/already_exited 或可信回执时才能终结。unknown、identity/provider 不可用和 stop timeout 保持待收敛，不能猜测退出。

4. application 只拥有一个周期 timer

LocalExecutionControlLifecycle 同时驱动完成通知、deadline/cancellation 单页扫描和低频 receipt cleanup。每个 application 只有一个 unref 周期 timer，没有每任务 timer、watcher、目录扫描或无界队列：

Profile	控制周期	控制页	cleanup 周期	cleanup 页	drain 页预算
edge	5 秒	4	5 分钟	8	2
standalone	1 秒	32	1 分钟	32	8

每次工作串行且不重叠；页、通知、停止等待和 drain 页数均有硬上限。cluster-control/worker 不装配该本机 lifecycle，其远端 Session/Lease/Attestation 继续使用独立 authority。

5. 停机顺序包含 execution drain

application 停止顺序固定为 admission close/drain → local execution stop/drain → injected stack stop → storage close。execution drain 只读取有界 active keyset，为尚无取消意图的 Attempt 先提交 shutdown cancellation，再按 exact handle 停止并终态化。已有 user/policy/timeout 意图必须保留，不能被 shutdown 覆盖。生命周期 stop 自身幂等；页预算、stop 证据或时间预算未收敛时返回 timed_out，但仍继续关闭后续 owner。

替代方案

1. 每个任务一个 timeout timer：任务数直接决定 timer/closure 数和停机竞态，拒绝。
2. Promise settle 直接写终态：内存事实无法跨重启，且绕过 receipt capability，拒绝。
3. 取消先 signal 后写数据库：数据库失败后无法证明意图与审计，拒绝。
4. 扫描 receipt 目录发现完成：空闲和大目录成本不可控，也无法证明 active authority，拒绝。
5. 复用 cluster CancellationDispatch/Lease：让路由设备携带多副本 authority 和驱动，拒绝。
6. 停机直接关闭 SQLite：仍运行的进程失去控制面与终态收敛路径，拒绝。

影响与未完成项

已完成：

• 共享完成处理器、回执认证、原子 Attempt/Run 双终态和迟到回执幂等清理；
• SQLite cancellation/deadline/active stable keyset source，无新 migration 或第二连接；
• deadline→durable timeout intent、user/policy/shutdown cancellation 与 exact process stop；
• dispatcher 内部完成通知、单 timer Profile lifecycle 和 application admission-first shutdown drain；
• 启动恢复复用同一个完成处理器；
• 真实 SQLite completion、deadline、user cancellation、shutdown drain、通知合并和幂等停止测试。

仍未完成：

• retry policy 的产品入口与安全重试协调；
• 加密 Secret provider、Artifact retention/read API 与可观测指标/告警；
• target executable、systemd/Docker/s6 controller 和 2.x cutover 产品流程；
• Linux x64/arm64、PID namespace、强杀/断电/ENOSPC 与固定物理路由器实机门禁；
• PostgreSQL/Remote Worker completion、expiry、cancellation 和 retry 对等生命周期。

因此本 ADR 关闭本机单次执行的 completion/cancellation/timeout/shutdown 纵向缺口，但不表示整个 3.0 target 已可默认接管存量任务。

验证

1. completion receipt 认证后原子写入 Attempt/Run 双终态和顺序事件，清理发生在提交之后。
2. cancellation 与 deadline 在 signal 前已有 durable intent；数据库失败、无 exact handle 或 stop unknown 时不写假终态。
3. due source 使用既有索引、稳定 keyset、最多 64 条；edge/standalone 只读取 4/32 条。
4. shutdown drain 先写 shutdown，保留已有 reason，并在 storage close 前停止 exact active execution。
5. dispatcher 不暴露 completion Promise，重复完成通知只消费一次 identity。
6. startup recovery 与在线 completion 使用同一处理器，迟到回执不能覆盖 cancelled/timed_out。
7. lifecycle 只拥有一个周期 timer、无任务级 timer/watcher，stop 调用幂等且有硬超时。
8. 本 ADR 落地时 dependency/source/lock、Profile vulnerability 和 application artifact 门禁包含第二十个 importer；ADR-0073 已将 local-secret 扩展为第二十一个。