qinglong/docs/adr/ADR-0488-cross-domain-reconciliation-completion-fence.md

# ADR-0488：跨领域 Reconciliation 完成围栏与目标重启授权

- 状态：Accepted
- 日期：2026-08-22
- 决策：D-394
- 关联：ADR-0482、ADR-0485、ADR-0486、ADR-0487

## 背景

D-392 把 reconciliation 拆为固定八个领域，D-393 已实现首个 Automation plan、review、apply、verify 与 rollback。然而 instance lineage 在 Automation apply 后只停在 `reconciliation_automation_applied`，target start authority 又只接受早期 `legacy_stopped|target_active|manual_required`。系统因此同时存在两个缺口：

- 没有一个证据能证明八个领域都已终结，不能安全地把单领域 apply 当作整体完成；
- 即使八个领域都明确选择 no-effect，也没有合法状态可进入 target generation 2。

直接允许 `reconciliation_automation_applied` 重启是不安全的。真实迁移后的目标 SQLite 仍可能在 Secret/Config、Run History、Identity/Policy/Audit 或 Unknown 领域包含 `manual_external`；Automation 写入成功不等于这些领域已经被处理。另一方面，永久拒绝 all-no-effect 场景会让完成了人工 review、明确保留 Target/排除 Legacy 的部署无法继续。

## 决策

### 1. 完成是独立的跨领域状态，而不是某个 adapter 的别名

实例谱系新增唯一终态 `reconciliation_completed`。它只能从以下 source head 前进：

- `reconciliation_application_planned`：八个领域全部为 `no_effect`；
- `reconciliation_automation_applied`：只有 Automation 为 `adapter_required`、其余七个领域全部为 `no_effect`，且 Automation decision、apply receipt、当前 target snapshot 与 head 完整一致。

任何 `manual_external|adapter_and_manual`、非 Automation 的 `adapter_required`、Automation rolled-back 或证据漂移都失败关闭。当前完整迁移数据库通常仍包含多个受保护的 manual 领域，因此 Automation apply 不会被误判为 restart-ready；backup 继续保留，等待后续领域 adapter 或显式 rollback。

### 2. 调用方不能自报八领域完成

`local.deployment.reconciliation.complete` 只接收 completion/application/head digest，以及可选的 Automation apply digest/identity。coordinator 重新打开已封存的 application terminal，并严格按 D-392 固定顺序从 plan 推导八项 domain evidence：

- `no_effect` 绑定 application domain `summaryDigest`；
- Automation adapter 绑定真实 `applyDigest`。

receipt 固定包含八项、`adapterCount=0|1`、application plan、source head、实例 identity、generation、时间与自身 digest。调用方不能提交任意 domain 数组、路径、row body、Secret、reviewer 或 credential 作为完成声明。

### 3. Receipt-first、head-second、重资产最后回收

mutation 顺序固定为：

1. 重新验证 application、可选 Automation apply、当前 target snapshot 与 source head；
2. no-replace 发布 completion receipt，并封存为 `0400`；目录封为 `0500`；
3. CAS 前进到 `reconciliation_completed`；
4. 仅在 completed head 已 durable 后回收 Automation rollback backup，并把空 `backup/`、`rollback-work/` 封为 `0500`。

receipt publish、seal、head advance 或 backup collection 任一响应丢失都可由相同 exact command 重放。顺序禁止在 head 仍是 applied 时删除 backup；若在 head 完成后、回收前崩溃，重放只继续收紧存储，不恢复 rollback authority。

`local.deployment.reconciliation.complete.verify` 全程只读：验证 sealed receipt、八领域推导、application/Automation binding、当前 target snapshot、completed head 与已经收敛的存储形态，不修复漂移。

### 4. 直接 Target 重启只接受完成围栏

Docker target authority 继续拒绝 `reconciliation_application_planned`、`reconciliation_automation_applied` 和所有 manual/rolled-back 中间态；只有 `reconciliation_completed` 能重新进入 `target_active`，且调用方必须使用下一 generation。

Service Manager 虽然复用同一个 head assertion，但既有 v1 intent 只绑定 prior service journal `previousRecordDigest`，没有独立的 expected completion-head digest；其后续 compare-and-swap 因而继续拒绝 completed head。D-394 不通过忽略该比较来伪造兼容性。该后续边界现由 D-395/ADR-0489 的 v2 intent 完成：systemd/OpenRC 必须同时绑定 prior service record、exact completion head 与 completion digest 才能获得 restart-ready authority；v1 仍失败关闭。

### 5. 部署规模与代码边界

实现位于既有 `@qinglong/local-owner-cli` 的 `deployment/reconciliation/completion/` 子域，按 contract/evidence/coordinator 三个职责文件组织；没有新拆 workspace package，也没有把实现平铺到 `src/` 根。

- Edge/Standalone：无 daemon、timer、watcher、listener、Pool 或常驻缓存；receipt 上限 64 KiB、completion catalog 上限 64，SQLite snapshot/hash 复用固定内存实现；completed 后同步释放数据库等量 rollback backup。
- Cluster：本 ADR 只定义 Local SQLite authority。PostgreSQL/多副本必须使用独立的事务、snapshot 与 HA evidence，不能复用本机文件路径或把 Local receipt 当成 Cluster completion。

## 被拒绝的替代方案

### Automation applied 直接允许重启

拒绝。它会跳过其余七个领域，尤其会把 Secret custody、append-only history 和 Identity/Policy manual decision 静默吞掉。

### 调用方提交 `completedDomains[]`

拒绝。自由数组无法证明来源、顺序、摘要和 current head，容易把 stale 或伪造 claim 变成 restart authority。

### 先删除 backup 再写 completed head

拒绝。head CAS 失败会留下 applied 状态却失去 rollback source，形成不可恢复的部分提交。

### 为完成围栏新增独立 package/service/GC timer

拒绝。该职责没有独立部署和扩缩容边界；额外 package、进程或周期扫描只会增加路由设备的安装元数据、RSS、唤醒和竞态。

## 验收证据

- completion focused `2/2`：覆盖 all-no-effect 的 receipt/seal/head 三个 response-loss 窗口、只读 verify、CLI content-free、直接 target generation 2 状态转换；同时覆盖 Automation 已 apply 但其他领域仍 manual 时拒绝完成、拒绝 target restart，并保持 `0400/0500` backup authority。
- 完整 Local Owner `268 total / 261 pass / 7 conditional skip / 0 fail`；18-package clean build 与逐包测试 exit 0。
- dependency/package boundary 组合门 `70/70`，Edge import audit 为 122 modules、0 forbidden；workspace 保持 18 packages、无 single-source/shallow package；Local Owner 为 `172 source / 171 nested / 1 root binary entry`。
- 不新增 production dependency、SQL migration、daemon、timer、watcher、listener、Pool、PostgreSQL role/ACL 或 cluster workload。
- Secret/Config、Run History、Plugin Package、AI/Tool、Identity/Policy/Audit、Unknown 的 terminal adapter，以及固定真实 systemd/OpenRC completed restart 演练仍是后续工作；Service Manager v2 completion-head binding 已由 D-395/ADR-0489 完成，D-394 本身不倒填该结论。