qinglong/docs/adr/ADR-0486-bounded-automation-row-reconciliation-plan.md

ADR-0486：有界 Automation 行级 Reconciliation Plan

• 状态：Accepted
• 日期：2026-08-21
• 决策：D-393
• 关联：ADR-0002、ADR-0482、ADR-0483、ADR-0484、ADR-0485

背景

ADR-0485 只把 signed schema/table review 汇总为八领域 application plan。automation=adapter_required 说明必须进入领域 adapter，却不能证明任一 Legacy Crontabs 行能够安全写为 3.0 TaskDefinition/Trigger。直接把表级 adopt_legacy 解释为批量 INSERT 会遗漏：

• command/schedule/timezone 与 shell compatibility；
• Project 重绑定后的 Task ID 冲突；
• target current revision 的稳定内容身份；
• malformed、manual-only 与 security-review 行；
• Edge 上逐行材料的内存和文件预算；
• review file、sealed bundle 与 application head 的 exact binding。

既有 Legacy Crontab adoption 已实现有界分类与 canonical Task/Trigger candidate。D-393 应复用该语义，而不是建立第二套转换器；但首次 adoption 尚不知道 D-392 application、captured target 冲突和后续 backup/rollback，因此不能直接调用其 publication。复用只允许通过 @qinglong/local-admin/adoption-inspection 的窄化只读子路径，包根继续隐藏 candidate；依赖审计只对 D-393 rowPlan.ts 精确放行该子路径，不能借此取得 Local Admin 的其它写 authority。

决策

1. 先发布逐行计划，不取得 DML authority

Local Owner 在既有 deployment/reconciliation/application/automation/ 下提供：

• local.deployment.reconciliation.automation.plan；
• local.deployment.reconciliation.automation.verify。

plan 只允许 exact reconciliation_application_planned head。它重新验证 application terminal、signed review 所绑定的原始 decision file、canonical sealed facts，以及 Legacy Crontabs table 的 adopt_legacy|retain_both 方向授权。没有 Automation adapter action、decision file digest/count 漂移、hot journal 或 unpaired sidecar 都失败关闭。

2. 逐行 NDJSON 为私有、内容最小化证据

每行重新使用既有 Legacy Crontab classifier，并记录：

• row ordinal、source digest、classification/reasons；
• proposed Task ID、enabled、trigger count；
• Task/Trigger candidate digest，而不是 command/spec 正文；
• target 当前 Task 的 absent，或 current revision/content digest；
• review_adopt | review_skip_conflict | manual_required requirement；
• domain-separated row plan digest。

文件不保存 command、Task name、reviewer、credential、Secret、路径或 target row body。header 绑定 application/review/decision/bundle/head/Project/timezone，footer 绑定 inventory、row-set、计数和 outcome。外部 receipt 再绑定完整 plan file SHA-256 和字节数。

3. 冲突矩阵

Legacy candidate	Target Task ID	计划 requirement	本阶段含义
可转换	absent	review_adopt	可进入后续签名行级裁决
可转换	occupied	review_skip_conflict	不覆盖 target；后续必须显式 skip/rename/manual
不可转换	任意	manual_required	不获得自动写入资格

表级 retain_both 不能自动改名，表级 adopt_legacy 也不能覆盖已存在 Task。后续 apply 必须消费 exact row plan digest 和独立签名裁决。

4. Edge/Standalone 预算

• plan 按 NDJSON 流式写入，单行最多 64 KiB；
• Edge 文件最多 8 MiB，Standalone 最多 32 MiB；
• Legacy 与 target 各只打开一个 readonly SQLite handle；
• Edge 每 handle cache 2 MiB，总 SQLite cache 约 4 MiB；Standalone 每 handle 8 MiB；
• 不把全量 Task ID 或 candidate 放入内存 Set/JSON array；
• 不新增 package、依赖、binary、daemon、timer 或 listener。

超出 byte/row/schema budget 时失败关闭，不以截断计划换取成功。

5. Crash、replay 与 seal

plan 使用 owner-only stage、fsync、hard-link no-replace publication。plan、receipt、terminal seal 与 instance-head CAS 四个窗口都允许 exact replay：

• 已发布 plan 会用重新派生的 exact bytes/digest 验证；
• 已发布 receipt 会验证 plan size/hash 和 command binding；
• terminal 文件为 0400、目录为 0500；
• head 只允许 reconciliation_application_planned → reconciliation_automation_planned；
• verify 只读，不打开 live target、不执行 DML、不修复 drift。

6. 尚未授予的能力

reconciliation_automation_planned 不等于 applied、rollback-ready 或 reconciliation-complete。它不允许启动 target、删除 Legacy、写 Task/Trigger、创建 Secret、复制日志或解释其它领域。

下一切片仍必须完成：

1. exact row-plan-bound 的独立签名行级裁决与再次强认证；
2. 在同一 target write fence 内生成并验证写前 SQLite backup；
3. Project Policy fence、幂等 Task/Trigger transaction 与 response-loss replay；
4. post-apply exact evidence、无后续写保护和全库 rollback；
5. Edge 磁盘峰值及 Cluster/PostgreSQL 的独立并发/HA 语义。

被拒绝的替代方案

直接调用首次 Legacy adoption

拒绝。它没有 D-392 application binding，也没有 captured target collision snapshot 与 rollback authority。

把 target Task ID 全量载入 Set

拒绝。内存随 target 规模增长，低配路由设备的峰值不可控。当前实现以有界双 readonly handle 对每个 candidate 做索引查询。

在行计划保存 command/spec

拒绝。人工裁决只需要 classification、reason、digest 与冲突证据；command 正文扩大泄露面和计划文件预算。apply 必须从 exact sealed source 重新派生 candidate。

自动为冲突 Task 改名

拒绝。改名会改变外部引用、Trigger ID 和用户可见 identity，必须成为明确行级决定，不能由表级 retain_both 推导。

验收条件

ADR 只有在以下证据全部通过后才可改为 Accepted：

1. exact signed review 与 Crontabs table disposition 被重新验证；
2. 无冲突、冲突、manual/malformed、空表、timezone 与 byte budget 有测试；
3. plan/receipt/seal/head response-loss exact replay 与篡改拒绝有测试；
4. 新状态对既有 capture/plan/review/application/cutover 状态机无回归；
5. Local Owner、tracked backend、18-package、架构与 artifact gates 通过；
6. GitNexus detect_changes 仅报告预期 Automation/Cutover 影响。

验收证据（2026-08-21）

• Automation 聚焦套件 40 total / 38 pass / 2 conditional Docker skip / 0 fail，覆盖无冲突、target collision、空表 no_effect、缺失 timezone 转 manual、64 KiB 注入预算失败、四个 publication response-loss 窗口、plan tamper 与 CLI 脱敏；真实 Docker sealed reconciliation 2/2 通过。
• 完整 Local Owner 262 total / 255 pass / 7 conditional skip / 0 fail；18-package clean build/逐包测试退出 0；backend build 通过，tracked backend 1541 total / 1539 pass / 2 conditional skip / 0 fail。
• Edge import、Cluster dependency、package boundary、service-manager bridge、deployment lock surface 与 fresh readiness 定向门全部通过；workspace 保持 18 packages，singleSourcePackages=[]、shallowSourcePackages=[]。Local Admin 为 46 source / 45 nested / 1 root public export，Local Owner 为 161 source / 160 nested / 1 root binary entry，新增实现均在既有领域目录。
• 十四档 Edge/Standalone artifact audit 全部 compatible。基础 Edge/Standalone 精确保持 2,611,978 / 2,612,056 bytes、319 files、58 modules；D-393 一次性 authority 没有进入低配常驻闭包。
• GitNexus staged audit 为 15 files / 56 symbols / 0 affected execution flows / LOW；next 相对 develop 的 3464 files / 48714 symbols / 269 flows / CRITICAL 是 3.0 孵化分支累计风险，继续单独保留，不能归因于本切片。
• 本切片不修改 SQL migration、PostgreSQL role/ACL、Pool、Cluster 拓扑或 HA 运维语义，因此不重复占有 PostgreSQL HA 证明；写前 backup/apply/rollback 切片引入 SQL 写语义时必须重新选择相应数据库门禁。