qinglong/docs/adr/ADR-0036-approved-action-profile-aware-runtime-lifecycle.md

ADR-0036：Approved Action Profile-aware 有界 Runtime Lifecycle

• 状态：Proposed
• 日期：2026-07-19
• 关联：QL-RFC-0001、ADR-0008、ADR-0032、ADR-0033、ADR-0034、ADR-0035

上下文

ADR-0032/0033 已分别提供一页有界的 Approved Action dispatcher 和 evidence-only recovery reconciler，但它们故意不拥有 timer 或进程 hook。没有显式 lifecycle 时不会自动工作；直接为两者各启一个固定频率 timer，又会在小型路由器上造成并发 SQLite 写竞争、重复唤醒和停机难以 drain，在 cluster-control 上则可能误把单机 SQLite 编排当作多副本实现。

QingLong 的部署跨度从低内存路由/NAS 到独立服务器和集群控制节点。相同状态机可以共享，但 cadence、页大小和每周期预算不能共享一个无条件默认值。

因此需要一个默认不可达、profile-aware、单 timer、两阶段串行的 runtime lifecycle；它只编排现有有界能力，不扩大 handler、evidence provider 或数据库 adapter 的 authority。

决策

1. 一个本机 lifecycle 串行 recovery 与 dispatch

ApprovedActionRuntimeSupervisor 的单周期顺序固定为：

1. recovery phase：调用 ApprovedActionRecoveryReconciler.reconcileBatch；
2. dispatch phase：调用 ApprovedActionDispatcher.dispatchBatch。

recovery 优先是 fail-closed 边界。如果 recovery due index 无法读取或周期抛错，本周期停止，不继续领取并执行新的 Approved Action。单周期内两个 phase 不并发，避免 SQLite 上 recovery resolution 与新 start barrier 争夺写锁。

这不表示每次 recovery 必须清空积压。两个 phase 都有独立的 page size、max pages 和 keyset cursor，达到预算立即停止。

2. 页预算和 cursor 都有硬上限

每个 phase：

• page size 继续受现有 domain hard cap 64 约束；
• max pages 范围为 1..64；
• 每页汇总只累计固定数值字段，不收集 dispatch 列表、错误文本或证据内容；
• truncated 且 cursor 前进时继续下一页；
• cursor 缺失或不前进时以 cursor_stalled 停止并报告 remaining；
• 达到 max pages 时以 page_limit 返回下一 cursor。

lifecycle 只在成功周期后更新内存 resume cursor。周期失败保留原 cursor，下一 cadence 重试同一边界；进程重启后 cursor 可以从头恢复，因为 due 查询与 claim/fence 都是幂等、有界的，cursor 不是唯一持久事实。

3. edge 与 standalone 使用不同资源预算

本机 SQLite Profile 固定为：

Profile	interval	recovery budget	dispatch budget	单周期理论上限
edge	30 秒	1 × 8	1 × 8	16 条
standalone	2 秒	2 × 16	4 × 32	160 条

两档 stop timeout 都为 5 秒，initial delay 为 0。这里的“条”是扫描/处理上限，不承诺每条都会写数据库；空页只做有界索引查询。

edge 的目标是限制唤醒、内存和 SQLite 写放大，不追求低延迟。standalone 提供更快收敛，但仍有硬页预算，不能因为积压进入无界循环。

4. lifecycle 只有一只非重叠 timer

ApprovedActionRuntimeLifecycle：

• 构造后 inert，只有显式 start() 才调度；
• 同时最多存在一只 timer 和一个 in-flight cycle；
• timer 调用 unref()，不单独阻止进程退出；
• 下一次 cadence 只在当前 cycle settle 后调度，不做固定间隔重叠；
• stop() 立即清 timer，并最多等待配置的 stop timeout；
• metrics/diagnostic callback 抛错只报告，不形成 scheduler failure loop；
• interval 最小 250 ms、最大 24 小时，stop timeout 最大 60 秒。

没有 watcher、每 action timer、递归翻页、无界 Promise 集合或后台子进程。

5. cluster-control 与 worker 不使用本 lifecycle

localPrimaryResourcePolicy() 继续只接受 edge/standalone；cluster-control 和 worker 会在取得配置前拒绝。cluster-control 未来复用 Supervisor 的 phase 语义，但必须使用 PostgreSQL repository、共享 evidence、独立多副本 ownership/leader 策略和集群指标；不能装配 SQLite lifecycle。worker 不拥有 ApprovalRequest、dispatch 或 recovery control-plane 表。

6. 当前仍不接 production activation

本切片只增加 Supervisor、Lifecycle、Profile resource policy 和 contract tests，没有修改 manual Primary activation stack、back/app.ts、loader、API 或 legacy service。生产装配前仍需要：

• immutable plan resolver、handler/provider registry 与显式启用 manifest；
• startup ordering，确保 migration、authentication、Policy、Artifact/Secret gate 先完成；
• backlog、oldest age、phase duration、cursor stalled、manual-required 和 unavailable 指标/告警；
• admission gate，在 recovery/manual backlog 或存储异常时停止新增高风险动作；
• 有界 drain 的真实 shutdown 编排与失败审计；
• edge 实机 CPU/RSS/SQLite 写放大/断电门禁；
• PostgreSQL cluster-control adapter 与多副本竞争 contract。

影响

正面影响：

• 路由器只付出一只 timer 和严格有界的周期成本；
• recovery 故障不会继续扩大新的不确定副作用；
• standalone 可以在相同状态机下使用更高吞吐预算；
• keyset cursor 防止单周期无界扫描，并能跨周期继续积压；
• cluster-control/worker 误装本机 SQLite 控制面继续 fail closed。

代价与风险：

• recovery-first 意味着 recovery 存储持续失败时新动作也会暂停；这是有意的安全降级；
• cursor 只在内存保存，重启会从 due index 起点重新扫描，依赖 claim/fence 幂等；
• edge 积压收敛较慢，需要产品显示 backlog 和 oldest age；
• 当前没有 production registry/activation，代码存在不代表 Approved Action 已自动运行。

未选择的方案

1. dispatcher/reconciler 各一只 timer：小设备产生重叠唤醒和 SQLite 写竞争，拒绝。
2. 先 dispatch 后 recovery：恢复面故障时仍扩大新副作用，拒绝。
3. 每周期清空所有页：积压可形成无界 CPU、内存和写放大，拒绝。
4. 固定 1 秒适配所有部署：路由器资源预算不成立，拒绝。
5. cursor 持久化到业务表：cursor 不是正确性事实，额外写放大和 fencing 复杂度暂不值得，拒绝。
6. cluster-control 直接复用 SQLite lifecycle：多副本可见性和锁语义错误，拒绝。
7. 构造时自动 start：无法保证 migration、Policy、Secret/Artifact 和 shutdown 顺序，拒绝。

验证要求

• recovery phase 总在 dispatch 前；recovery list/read 失败时 dispatch 调用数为 0；
• phase page size/max pages、cursor 前进和 stalled 都有 contract tests；
• edge/standalone cadence 与预算不同，返回 policy 是深拷贝；
• cluster-control/worker 请求本机 policy 时拒绝；
• lifecycle 构造后无 timer，重复 start 不重复调度；
• 慢 cycle 不重叠，下一 timer 只在 settle 后建立并调用 unref；
• page-limit cursor 在下一周期恢复，完整周期清除 resume cursor；
• stop 清理 pending timer，并对 in-flight cycle 有硬等待上限；
• callback 抛错不形成 hot loop，非法 interval/page/timeout fail closed；
• production reachability 搜索证明 lifecycle 未被 app/loader/API/service 导入；
• Node 22 兼容门禁与固定 Node 24 目标门禁均通过。