qinglong/docs/adr/ADR-0485-reconciliation-application-coordinator.md

ADR-0485：Reconciliation 应用协调器与领域 Adapter 边界

• 状态：Accepted（D-392 已实现并完成门禁）
• 日期：2026-08-21
• 关联 RFC：QL-RFC-0001 D-05、D-06、D-17、D-64、D-87、D-184、D-259、D-383、D-389、D-390、D-391、D-392
• 关联 ADR：ADR-0482、ADR-0483、ADR-0484
• 细化：ADR-0484 的签名人工裁决消费边界

背景

ADR-0484 已把密封 reconciliation plan 转换为逐事实、强认证 User 签名的 review authorization，但该 authorization 仍只表达 operator 对 schema object/table 事实的选择。它没有定义任何领域的行级兼容、幂等键、写入顺序、备份、回滚或外部资产语义。

直接让通用导入器消费 review 会产生错误的授权提升。例如 Automation 表被选择为 adopt_legacy，并不意味着表内每个 Legacy shell command 都能转换为 3.0 TaskDefinition，也不能证明目标 task id、timezone、disabled state 和 trigger 没有冲突。Secret、Run history、 Plugin package、AI/Tool 与 Identity/Policy/Audit 的安全语义差异更大，不存在一套可信的通用 DML。

D-392 因此只建立一个持久、内容无关的应用顺序根。它把签名 decision stream 汇总成固定八领域计划，为后续 adapter 提供唯一 fence， 但不执行迁移。

决策

1. 增加独立 application coordinator 状态机

既有 ql3-local-deploy 增加三个显式私有命令：

local.deployment.reconciliation.application.prepare
local.deployment.reconciliation.application.commit
local.deployment.reconciliation.application.verify

状态以 instance head CAS 推进：

reconciliation_reviewed
  → reconciliation_application_prepared
  → reconciliation_application_planned

application.prepare 必须绑定 exact reviewId、reviewDigest 和 reviewed head digest。它建立唯一 application fence 后，以 no-replace 方式发布 intent。第二个 application、旧 review replay、rollback、restart 或越级 commit 都必须失败关闭。

reconciliation_application_planned 只表示领域执行顺序已固定，不表示 reconciliation 完成、数据库已迁移或 target 可以重启。

2. Application plan 固定为八领域内容无关摘要

coordinator 重新验证 D-391 的 sealed review directory、authorization HMAC、issuer keyring、review/receipt binding 和 decision-set digest， 并在读取签名 NDJSON 时以固定 counter 统计：

schema_lineage
automation
secret_and_config
run_history
plugin_package
ai_and_tool
identity_policy_audit
unknown

每个领域只保存 Legacy/Target 两侧的 decision count、固定 disposition counts、summary digest 与 action：

no_effect | adapter_required | manual_external | adapter_and_manual

总体 outcome 为：

no_effect_ready | adapter_required |
manual_required | adapter_and_manual_required

plan 不保存对象名、表名、路径、fact digest、row value、command、schedule、Secret、credential、Prompt/Tool payload、Artifact、日志或 reviewer identity。它最多 64 KiB，domain 数固定为 8，内存只使用固定 counters 与 64 KiB 读取缓冲。

3. 修正 disposition 的数据库方向语义

D-391 已限制 blocked domain，但原始校验没有拒绝数据库方向矛盾的选择。D-392 明确：

• Legacy fact 不允许 retain_target；
• Target fact 不允许 adopt_legacy 或 exclude_legacy；
• retain_both、defer 与 manual_external 仍受既有 domain/blocked 规则约束；
• informational fact 仍不得出现在 decision stream。

该规则在签名发布前对重新派生的 canonical fact 生效，不依赖 diagnostics page。

4. 持久化、封存与崩溃恢复

applicationRoot 必须与 deployment、capture、plan、review root 两两不重叠；issuer keyring 必须位于 deployment root 的真后代。catalog 最多 保留 64 个 application directory，每个目录只含：

intent.json
plan.json
receipt.json
staging/

intent、plan、receipt 使用 no-replace publication、stable file identity、file/directory fsync 和 digest binding。prepare head、plan、receipt、 terminal seal 与 planned head 后的 response loss 均必须 exact replay；冲突内容不允许覆盖或自动清理。terminal 文件收敛为 0400，目录与 空 staging 收敛为 0500。专用 terminal reader 在读取前后复核 owner、mode、link count、device/inode、size、mtime/ctime，不放宽通用 0600 command-file policy。

5. Verify 完全只读

verify 只读取 sealed application evidence、sealed review authorization、issuer verification key 与 instance head。它不创建、替换、修复或 清理文件，不打开 Legacy/Target SQLite，不执行 checkpoint、SQL/DML、Secret 解密、Docker/init/service/network 或后台 retry。

应用 coordinator 的 prepare/commit 同样不得打开 SQLite。它消费的是 D-391 已签名、内容完整性受保护的 decision stream，而不是重新读取 数据库。每个未来 adapter 在写入前仍必须重新验证 exact application plan/head 和自己的领域输入。

6. 领域 Adapter 必须独立授权和回滚

D-392 不提供通用 apply。后续每个 adapter 至少要单独定义：

• 可接受的 source/target row schema 与兼容矩阵；
• Project/Policy/Owner authority 与需要重新认证的操作；
• 幂等 identity、冲突规则、写入顺序和 response-loss replay；
• 写前 backup、失败保全、rollback 与不可逆边界；
• Secret custody、append-only history、外部文件/OCI/KMS 等领域特有语义；
• Edge 的 RSS/I/O/磁盘峰值与 Cluster 的并发、租约和 HA 语义。

第一候选为 Automation adapter，但它必须先生成逐行、可审查、可回滚的 TaskDefinition/Trigger 转换计划，不能把 D-391 的表级选择直接解释为 批量 INSERT/UPDATE。

7. Package 与部署边界

实现内聚在既有 @qinglong/local-owner-cli/src/deployment/reconciliation/application/，按 contract、plan、coordinator 三个职责文件组织。 不新增 workspace package、production dependency、binary、daemon、timer、watcher、listener 或 socket，也不把文件平铺到 package src/ 根。基础 Edge/Standalone runtime artifact 不应携带一次性 application authority；Cluster/PostgreSQL/Kubernetes 不读取 Local application root。

当前实现进度

D-392 已实现三条命令、两阶段 instance CAS、八领域 content-free plan、signed authorization domain counters、数据库方向校验、0400/0500 terminal seal、完整 response-loss replay 和只读 verify。聚焦 reconciliation 套件为 35 total / 33 pass / 2 conditional Docker skip / 0 fail；完整 Local Owner 为 257 total / 250 pass / 7 conditional skip / 0 fail；Git 跟踪 backend 为 1541 total / 1539 pass / 2 conditional skip / 0 fail。包含用户未提交测试的当前工作区 backend 也以 1542 total / 1540 pass / 2 conditional skip / 0 fail 通过。18-package clean build/逐包测试、八项架构/部署审计与真实 Docker readonly reconciliation 2/2 全部通过。

十四档 artifact audit 全部 compatible；基础 Edge/Standalone 精确保持 2,611,978 / 2,612,056 bytes、319 files、58 loaded modules，证明一次性 application authority 未进入低配常驻闭包。workspace 仍为 18 packages，singleSourcePackages=[]、shallowSourcePackages=[]；Local Owner 为 158 source / 157 nested / 1 root binary entry。新增 3 个生产源码全部位于既有 deployment/reconciliation/application/，没有新增 package、 dependency、binary 或常驻对象。

本切片没有 SQL、SQLite open、数据库 schema、PostgreSQL driver/ACL/role/Pool、Cluster deployment 或 HA 拓扑改动；仍按 operator 授权额外 重跑 PostgreSQL 18.6 arm64 physical HA，以 146 gates、timeline 1 → 2 通过。private evidence SHA-256 为 632d71f2a5b33cf657476fbe41702064b609b12cdf2382bcddaef06f4d08279f，独立 evidence audit 无 finding，临时 Docker container/network 已 清理。该证明是额外回归证据，不把 Local application coordinator 解释为 Cluster reconciliation authority。

被拒绝的替代方案

让 D-391 review 直接调用 Automation adoption

拒绝。D-391 是 schema/table fact 授权，既有 adoption 是逐行首次接管协议；二者的冲突、幂等和 rollback 语义不等价。

为八个领域立即各建一个 package

拒绝。尚未形成独立发布、依赖或生命周期边界，会制造单文件/浅层 package。领域 adapter 先在现有 owner composition 的嵌套目录孵化，只有 出现稳定复用边界后才考虑拆包。

把全部 decision 加载成内存 JSON

拒绝。Edge 路由设备不能让内存随 schema 规模增长；签名验证与 domain summary 必须流式、固定缓冲。

把 application plan 当作 restart authority

拒绝。计划没有证明任何 adapter 已成功执行，也没有证明 Secret、历史或外部资产已收敛。

验收条件

1. 只有 exact reviewed head/review digest 可建立唯一 application fence；第二 application、rollback 与 restart 被阻断。
2. signed authorization 被重新验证并汇总为固定八领域、双数据库、固定 disposition counters；全局与领域计数严格守恒。
3. Legacy/Target 的方向矛盾 disposition 在签名前失败；blocked/informational 规则不回退。
4. application plan/receipt 不包含名称、路径、fact digest、row value、command、Secret 或 reviewer identity，且 plan 不超过 64 KiB。
5. prepare、plan、receipt、seal、head 的全部 response-loss 窗口 exact replay，竞争 application 失败关闭。
6. terminal 文件为 0400、目录为 0500；verify 只读且不打开 SQLite、不写数据库、不调用服务或网络。
7. 不新增 package/dependency/binary/常驻对象，不平铺 package src/；Edge 基础 closure 不增长。
8. 聚焦、Local Owner、tracked backend、18-package、架构、Docker 与十四档 artifact 门通过后，ADR 才可改为 Accepted 并阶段提交。

未包含

• Automation 或其他领域的行级转换、SQL/DML、备份与 rollback；
• Secret 解密/重加密、Run history 合并、Plugin/AI 外部资产复制；
• reconciliation completion、target restart 或 Legacy source 删除；
• Cluster/PostgreSQL/Kubernetes reconciliation；
• 固定物理 Edge/NAS 的断电、FTL 写放大与迁移峰值证明。