qinglong/docs/adr/ADR-0483-sealed-reconciliation-bundle-domain-plan.md

# ADR-0483：密封 Reconciliation Bundle 的有界数据域计划

- 状态：Accepted（D-390 已实现）
- 日期：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
- 关联 ADR：ADR-0064、ADR-0094、ADR-0095、ADR-0194、ADR-0201、ADR-0314、ADR-0315、ADR-0482
- 细化：ADR-0482 第 3、5、7 节的 terminal asset layout 与只读消费者契约

## 背景

ADR-0482 已把 stopped `reconciliation_required` 的 target、Legacy source、recovery 和 lineage 冻结为不可变 bundle，但
`reconciliation_captured` 只证明原始字节可恢复，不说明两侧哪些数据域发生变化、哪些事实可映射、哪些只能保留或人工裁决。直接从
capture 跳到 import 会把“证据保全”错误提升成写 authority，并且无法回答 3.0 Run、Secret、Plugin Package、AI、identity 与 audit
如何安全降级到 2.x。

当前 bundle 还使用 `target-main`、`target-wal` 等逻辑名作为实际文件名。SQLite 只识别 `<main>-wal/-shm/-journal`，因此下游若要
检查一致 snapshot，只能再复制一整份数据库或修改 bundle。前者会在路由器、NAS 和小闪存设备上制造不可接受的第二次空间放大；后者
破坏 ADR-0482 的不可变承诺。D-390 必须先修正物理读取契约，再建立严格只读、固定内存和固定输出的领域计划。

## 决策

### 1. Capture schema v2 使用 SQLite 可识别的固定物理名并密封

manifest 继续只保存固定逻辑名，不保存输入绝对路径；实际 payload 使用固定映射：

| 逻辑名 | 物理名 |
| --- | --- |
| `target-main` | `target.sqlite` |
| `target-wal/-shm/-journal` | `target.sqlite-wal/-shm/-journal` |
| `legacy-main` | `legacy.sqlite` |
| `legacy-wal/-shm/-journal` | `legacy.sqlite-wal/-shm/-journal` |
| `recovery-main` | `recovery.sqlite` |

capture manifest/receipt 升为 schema v2，并把 activation 中的 `sourceSha256`、`targetSha256` 纳入内容无关 lineage projection 和
manifest。receipt 发布后、instance head 推进前，所有 asset 从 `0600` 收敛为 `0400`，assets directory 从 `0700` 收敛为 `0500`，
并 fsync 文件、目录及父目录。部分 chmod、receipt-response-loss 和 head-response-loss 均由同一 commit 收敛；terminal verify 只接受
完整密封状态。3.0 尚未发布，本 ADR 不为内部 alpha schema v1 增加双格式兼容或自动重写。

### 2. 只允许两种零复制 SQLite 读取方式

- main 无 `-wal/-shm/-journal`：使用 `file:...?...immutable=1` 与 `readOnly`；
- `-wal` 与 `-shm` 同时存在、无 `-journal`：使用普通 `readOnly`，依赖密封 mode 阻止 SQLite 改写 shm。

存在 hot journal、WAL/SHM 不配对、额外 sidecar、mode/owner/link/hash 漂移时，不打开数据库、不尝试 checkpoint/recovery，也不把 main
当作完整 snapshot；该数据库 inventory 固定为 `manual_required`。每次打开前后重验 manifest 中全部 bytes/hash 和 stat，任何变化失败
关闭。handle 固定 `defensive`、`trusted_schema=OFF`、`query_only=ON`、`temp_store=MEMORY`、`mmap_size=0`，禁止 extension、attach、
vacuum、DDL、DML 和网络。

### 3. 增加独立 plan prepare、commit、verify

既有 `ql3-local-deploy` 增加：

```text
local.deployment.reconciliation.plan.prepare
local.deployment.reconciliation.plan.commit
local.deployment.reconciliation.plan.verify
```

调用方显式提供独立私有 `planRoot`、UUID `planId`、`captureRoot/captureId`、exact `bundleDigest`、当前 instance head digest、
`legacyTimezone|null` 和时间。prepare 验证密封 bundle 与 `reconciliation_captured` head，以 CAS 推进为
`reconciliation_plan_prepared`，并在 `<planRoot>/<planId>` no-replace 发布固定 intent。planRoot 不得位于 deployment root、capture
directory 或任一 SQLite asset 内。

commit 只读取密封 bundle，发布固定 schema plan、terminal receipt，再以 plan digest 把 head 推进为 `reconciliation_planned`。
verify 只重验 terminal plan、receipt、bundle binding 与 head，不打开 SQLite、不创建/清理文件。prepare/commit response loss、plan/receipt/
head 崩溃窗口均 exact replay；不同 command 不能复用 planId。

### 4. Plan 只提供固定领域 summary 和 disposition

plan 固定包含以下有序领域，不保存 row value、command、Secret、credential、日志、业务标识或单条对象名称：

1. `schema_lineage`：两侧 catalog、migration/capability 与未知对象摘要；
2. `automation`：Legacy Crontabs 与 3.0 Task/Trigger/adoption ledger 的计数和基线漂移；
3. `secret_and_config`：Legacy Envs/Auths 与 3.0 Secret/data-directory adoption 的计数和 custody 缺口；
4. `run_history`：Run/Attempt/Event/Step 等不可逆历史；
5. `plugin_package`：install/materialization/publication/lifecycle/quarantine；
6. `ai_and_tool`：provider、prompt、Tool execution/output/key binding；
7. `identity_policy_audit`：Project、RoleBinding、credential、pepper、approval 与 audit；
8. `unknown`：不在固定分类中的 table/schema facts。

每个领域只返回 bounded counts、inventory digest 和以下 disposition 之一：

```text
aligned | legacy_changed | target_changed | diverged |
target_only | manual_required | unsupported
```

`aligned` 也不授予写入；`target_only` 表示必须保留 3.0 bundle 或由后续显式 exporter 处理；`manual_required/unsupported` 禁止自动计划。
只要未知 schema、hot journal、不完整 sidecar、未映射 Legacy facts、active/inconclusive Run 或 credential/Secret custody 缺口存在，整体
outcome 必须为 `manual_required`。本 ADR 不产生 `import_ready`、`rollback_ready` 或 `legacy_ready`。

### 5. Diff 使用已提交 baseline，不猜测语义等价

capture manifest 的 source/target baseline SHA-256 与 captured asset set 判定数据库级 `unchanged|changed`。target 内既有
`QingLong3LegacyAdoptions` 和 `QingLong3LegacyDataDirectoryAdoptions` 只提供已提交 adoption baseline；Task/Trigger current revision、
Secret version 和各领域 table count/digest 只用于保守分类。名称相同、数量相同或 JSON 看起来相似都不能自动视为等价。

Legacy timezone 是显式 reviewed input；若与可证明的 adopted trigger timezone 不一致则 `manual_required`。D-390 不解密 Secret、不读取
credential/token、不执行 Legacy command，也不构造 2.x SQL。逐对象 private diagnostics、人工选择与目标 adapter 由后续 ADR 定义，必须
消费 exact plan digest。

### 6. 低资源与 package 边界

实现继续内聚在 `@qinglong/local-owner-cli/src/deployment/reconciliation/` 的 `sealed-bundle/` 与 `planning/` 子目录，不新增 workspace
package、production dependency、binary、daemon、timer、watcher、listener、socket 或后台 retry。不得把新文件平铺到 package `src/`
根，也不得从 deployment planning import Local SQLite mutation/adoption authority。

内存上限为单个 SQLite handle、64 KiB hash buffer、固定八领域数组和不超过 64 KiB 的 plan builder。Edge/Standalone SQLite cache
分别不超过 2/8 MiB；schema object 上限 4,096，table 上限 512，领域 row count 只保留安全整数和总量，不把对象列表放入内存。plan
文件不超过 64 KiB。Cluster/PostgreSQL 不消费 Local bundle 或 plan。

## 被拒绝的替代方案

### 为分析再复制 target 与 Legacy 数据库

拒绝。最坏会在 capture 已占两份数据库后再增加两份，直接破坏路由器和小闪存设备的空间模型。

### 直接以 immutable 打开带 WAL 的 main

拒绝。SQLite immutable 会忽略 WAL，可能静默丢失已经提交但未 checkpoint 的事实。

### 让 readonly SQLite 使用可写 shm

拒绝。真实验证表明 readonly handle 仍可能改写 `-shm`；只有密封资产才能保持 bundle hash 不变。

### 从表名相似自动生成回灌 SQL

拒绝。相同名称不证明 Project、revision、Policy、Secret custody、append-only history 或幂等身份等价。

### 把完整 row diff 写入 plan

拒绝。会泄漏敏感内容、产生无界内存/文件，并把 inventory 偷换成未审批的迁移 payload。

## 验收条件

1. Capture v2 固定物理名、0400/0500 密封、baseline digest 与全部 crash replay 可验证；v1 不被静默接受。
2. main-only immutable 与 WAL+SHM readonly 在 Linux/Docker 中可读取且前后 bytes/hash/stat 完全不变；hot journal/unpaired sidecar 零
   SQLite open 并稳定 `manual_required`。
3. plan prepare 只接受 exact `reconciliation_captured` bundle/head 并建立唯一 CAS fence；restart/rollback/第二计划不能越过。
4. commit 产生固定八领域、固定 disposition、≤64 KiB 的内容无关 plan/receipt；unknown、Secret/credential、Run 与未映射事实保守分类。
5. plan/receipt/head 各崩溃窗口和 response loss exact replay；verify 完全只读且不打开 SQLite。
6. 无 import、DML、checkpoint、service、Docker/init/network 副作用，无新增 package/dependency/常驻对象或跨包写 authority import。
7. Edge 固定 2 MiB cache、Standalone 8 MiB cache；完整 Local Owner/backend/package、架构、release、十四档 artifact 与真实 Docker
   readonly rehearsal 通过，基础 Edge closure 不增长。

## 实现与验证证据

D-390 已在既有 `@qinglong/local-owner-cli/src/deployment/reconciliation/` 内实现。`sealed-bundle/reader.ts` 只接受经 terminal
validator 验证的密封 capture：main-only 走 immutable readonly，WAL+SHM 完整配对走普通 readonly；hot journal、sidecar 不配对或
任一 stat/hash/mode 漂移均在 SQLite open 前失败关闭。`planning/` 以固定 contract、inventory、prepare/commit/verify 将 instance head
从 `reconciliation_captured` CAS 推进到 `reconciliation_plan_prepared`、再推进到 `reconciliation_planned`。plan 只包含固定八领域的
有界计数、digest、disposition 和保守 outcome，不保存表名、路径、row value、Secret、credential、命令或日志，也不产生 import authority。

实现没有新增 workspace package、production dependency、binary、daemon、listener、timer、watcher 或网络访问。workspace 仍为 18
packages，`singleSourcePackages=[]`、`shallowSourcePackages=[]`；Local Owner 为 `146 source / 145 nested / 1 root binary entry`，新增的
5 个源文件全部进入 `deployment/reconciliation/sealed-bundle|planning/`，没有回到 `src/` 根平铺。Edge/Standalone cache 固定为
2/8 MiB，hash buffer 与 plan 上限均为 64 KiB，schema/table 上限为 4,096/512。

验收结果：reconciliation 聚焦套件 `24 total / 22 pass / 2 conditional Docker skip / 0 fail`；真实 Linux/Docker main-only 与
WAL+SHM readonly/hash-stability rehearsal `2/2`；完整 Local Owner `246 total / 239 pass / 7 conditional skip / 0 fail`；tracked
backend `1540 total / 1538 pass / 2 conditional skip / 0 fail`；18-package clean build/逐包测试通过。Edge import、Cluster dependency、
package boundary、service-manager bridge、Local image、image release、release version 与 deployment-lock surface 审计均 compatible。

十四档 artifact audit 均 compatible。基础 Edge/Standalone 仍为 `2,611,978 / 2,612,056` bytes、319 files、58 modules；Adopted
仍为 `2,831,713 / 2,831,836` bytes、339 files、59 modules；Application+AI 为 `4,529,710 / 4,529,842` bytes、516 files、
144 modules；MCP 为 `7,337,910 / 7,338,018` bytes、805 files、228 modules。一次性 plan authority 未进入基础常驻闭包，也没有被
Cluster/PostgreSQL 消费。

## 未包含

- 逐对象明细分页、人工冲突选择和审批；
- 任何 Legacy/target 写入、Secret 解密、credential 导出或服务 restart；
- 自动 checkpoint、hot journal recovery 或损坏数据库修复；
- Cluster/PostgreSQL/Kubernetes reconciliation；
- 固定物理 Edge/NAS 的断电、FTL 写放大与介质销毁证明。