qinglong/docs/adr/ADR-0484-private-reconciliation-diagnostics-and-reviewed-decision.md

# ADR-0484：私有 Reconciliation 诊断与受认证人工裁决

- 状态：Accepted（D-391 已实现并完成门禁）
- 日期：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
- 关联 ADR：ADR-0064、ADR-0094、ADR-0095、ADR-0194、ADR-0201、ADR-0314、ADR-0315、ADR-0482、ADR-0483
- 细化：ADR-0483 的逐对象私有诊断、人工选择和审批边界

## 背景

ADR-0483 已把密封 capture 转换为固定八领域、内容无关的 `reconciliation_planned` summary。它能证明哪些领域一致、变化、分叉或必须
人工处理，但刻意不保存表名、业务标识、row value、Secret、credential、命令或日志。这样的 plan 适合审计、自动 fence 与低资源设备，
却不足以让 operator 判断具体对象应保留哪一侧、哪些事实必须交给专用 adapter、哪些只能在外部人工恢复。

不能通过扩大 plan 来解决该问题。把敏感明细写进 plan 会使长期 terminal receipt 变成数据副本，也会让 stdout、日志、Cluster consumer
和未来自动化意外获得内容读取面。另一方面，仅依赖一个 `0600` JSON 文件也不能证明真实用户完成了审阅；POSIX owner、容器 root 或遗留
脚本都不等同于近期强认证的人类 Owner。D-391 必须把“查看”“选择”“授权”和“执行”分开。

## 决策

### 1. Review 是独立状态机，不改变 plan 与 capture

既有 `ql3-local-deploy` 增加四个显式操作：

```text
local.deployment.reconciliation.review.prepare
local.deployment.reconciliation.review.diagnostics
local.deployment.reconciliation.review.commit
local.deployment.reconciliation.review.verify
```

prepare 只接受 exact terminal `planDigest`、`reconciliation_planned` instance head 和新 UUID `reviewId`，并以 CAS 推进：

```text
reconciliation_planned
  → reconciliation_review_prepared
  → reconciliation_reviewed
```

prepare 建立唯一 review fence 后，在 operator 显式提供的私有 `reviewRoot` no-replace 发布 intent。`reviewRoot` 与 deployment、capture、
plan root 必须两两不重叠；最多保留 64 个 review directory。target restart、Legacy rollback、第二个 review 和旧 plan 重放都不能越过
`reconciliation_review_prepared`。prepare response loss 必须 exact replay。

### 2. 诊断使用显式私有分页文件，不进入 stdout 或 terminal plan

diagnostics 每次只读取一个 database kind、一个固定领域和一个固定 fact kind，最多输出 64 条记录到 caller 显式提供的空目标文件。
目标父目录必须是当前 POSIX user 拥有的真实 `0700` directory；文件以 no-follow/no-replace、`0600`、file/directory fsync 发布。CLI
terminal response 只包含 `reviewId`、`planDigest`、page digest、记录数、完成标志和下一个有界 offset，不包含路径、对象名或对象 digest。

分页使用 `offset`，不是包含对象名的 cursor；每个 database 的 schema catalog 最多 4,096 条、table 最多 512 条，因此有界 OFFSET
不会形成无界扫描。page 绑定 exact `bundleDigest`、`planDigest`、review preparation digest、database kind、domain、fact kind、offset、
limit 和 bundle fingerprint。每次 SQLite open 前后继续执行 ADR-0483 的全资产 stat/hash 重验；main-only 与 WAL+SHM 的只读方式不变。

私有 page 可包含：

- schema/table 的名称、类型、所属表、领域、row count 与 fact digest；
- 已知 adapter 能安全解释的对象 ordinal、非 Secret 标签、状态、版本/时间边界和 canonical fact digest；
- `decision_requirement = informational | required | blocked` 与固定 reason code。

page 永不包含 SQLite schema SQL、Legacy command、日志、Secret/credential/token/key material、加密 envelope、Prompt/Tool payload、Artifact
内容或任意未设上限的 JSON。未知表只显示 catalog identity，不读取 row。Secret、credential、pepper、active/inconclusive Run、未知 schema
和缺少 custody 的事实固定为 `blocked`，不能被人工选择降级为自动可导入。

### 3. 决策文件是有界 NDJSON 流，不由 CLI 自动补全

operator 使用 diagnostics page 在外部形成 owner-only NDJSON review file。header 必须 exact 绑定 `reviewId`、profile、plan digest、
preparation digest 和 diagnostics contract version；后续每行只包含一个 required fact 的 ordinal、fact digest、disposition 与固定 reason。
允许的 disposition 为：

```text
retain_target | adopt_legacy | retain_both |
exclude_legacy | defer | manual_external
```

这些值只是未来 adapter 的 reviewed intent，不表示 SQL、文件或服务动作已经获准。`blocked` fact 只允许 `defer` 或 `manual_external`；
`run_history` 不允许删除/覆盖历史，`secret_and_config` 与 `identity_policy_audit` 不允许选择明文导出，`unknown` 不允许自动 adoption。
每个 required fact 必须按 canonical 诊断顺序出现且恰好一次，不接受遗漏、重复、额外或乱序 decision。

review file 使用稳定 descriptor 流式读取：每行不超过 64 KiB，hash buffer 64 KiB；Edge 总上限 8 MiB，Standalone 总上限 32 MiB。
解析期间重验 parent、device/inode、owner、mode、size、mtime/ctime；文件替换、hard link、symlink、增长、截断或语义重写全部失败关闭。

### 4. 人工批准必须来自近期强认证 User

commit 不能把“能运行 CLI”当作审批。Local Owner composition 必须使用既有 target Owner credential、pepper custody 与
`establishAuthenticatedLocalCommand` 建立近期强认证 User principal；认证 namespace 固定为 `local_reconciliation_review`。允许
`hardware | local_console | multi_factor` assurance，认证年龄最多 5 分钟，authorization lifetime 最多 30 分钟。Service、Agent、Worker、
弱认证或过期 principal 均拒绝。

授权沿用独立 issuer keyring 的 immutable generation、最多八把 verification key、私有路径和签名模型，但使用新的 reconciliation
domain separator 与 schema，不复用 Legacy Crontab receipt。issuer authority、credential fence、review file descriptor identity、sealed
bundle fingerprint 和 exact plan/head 在签名前后都必须再次确认。Edge 允许同一强认证 Owner 自审；本 ADR 不伪造双人审批。若未来
Standalone policy 要求 separation-of-duty，应新增 policy/ADR，而不是从设备 Profile 猜测。

### 5. Commit 重新派生事实并只发布有界 terminal evidence

commit 不信任 diagnostics page，也不要求 page 被持久保留。它从 exact sealed bundle 重新流式派生 canonical fact sequence，与 private
review file 逐条匹配，生成签名 authorization、固定 disposition/reason counts、decision-set digest 和 compact terminal receipt。
review root 只保存 `intent.json`、`authorization.ndjson`、`review.json`、`receipt.json` 与空 staging directory；authorization 是未来 adapter
读取人工选择的唯一内容载体，其余 terminal JSON 不复制对象名或业务标识。

authorization、review、receipt 和 instance head 的各个崩溃窗口均 no-replace exact replay。terminal 文件收敛为 `0400`，review root
和 staging 收敛为 `0500`；fsync 顺序覆盖 response loss。最后以 `reviewDigest` CAS 推进 `reconciliation_reviewed`。verify 只验证文件、
签名、exact plan/bundle/head binding 与曾在 commit 时有效的 reviewer authority，不重新打开 SQLite、不续期授权、不创建或清理文件。

### 6. Review completion 不授予 import、rollback 或 restart authority

`reconciliation_reviewed` 只证明一个强认证 User 对 exact fact set 给出了受约束选择。它不产生 SQL、不打开 target/Legacy 可写连接、不解密
Secret、不 checkpoint、不复制外部文件、不调用 Docker/init/socket/network，也不允许 target restart 或 Legacy rollback。下一阶段的
domain adapter 必须消费 exact `reviewDigest` 与 authorization digest，重新认证、重新授权、重新检查当前 head，并分别定义 backup、
prepare/commit、幂等 identity、冲突、response loss 和 rollback 语义。任何 adapter 都不能把 `defer/manual_external/blocked` 解释为成功。

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

实现继续内聚在 `@qinglong/local-owner-cli/src/deployment/reconciliation/review/`，可复用的只读 classifier 可留在相邻 planning 模块；不新增
workspace package、production dependency、binary、daemon、timer、watcher、listener、socket 或后台 retry，也不得把新源码平铺回 package
`src/` 根。review composition 可以使用既有 Local Owner authentication 与 issuer keyring primitive，但 diagnostics/contract 模块不得
import Local SQLite mutation、adoption publisher 或 runtime execution authority。

运行时最多一个 SQLite handle、一个 decision iterator、64 KiB hash/read buffer、64 条 page record 和固定八领域 counters。diagnostics
output 不进入基础 Edge/Standalone artifact；Cluster/PostgreSQL/Kubernetes 不读取 Local review root、authorization 或 reviewer identity。

## 当前实现进度

D-391 已完整实现 `review.prepare`、`review.diagnostics`、`review.commit` 与 `review.verify`。prepare/diagnostics 保持第一切片的 exact
plan/bundle/head fence、64 条私有分页、blocked fact 与 byte-exact replay；commit 新增 Edge 8 MiB、Standalone 32 MiB 的稳定 descriptor
NDJSON 流，逐条重新派生密封 bundle facts，不读取 diagnostics page。生产 composition 只通过新的 Local SQLite authentication-read
projection 读取 credential/pepper，并使用既有 `establishAuthenticatedLocalCommand` 建立最多 5 分钟的强 User principal。独立 issuer
keyring 最多八代 key，authorization 生命周期最多 30 分钟，签名前后重验 decision file、credential、keyring、plan、bundle fingerprint 和
prepared head。

authorization、review、receipt、seal 与 head 的每个 crash/response-loss 窗口均已覆盖；terminal evidence 收敛为 `0400/0500`，verify
复验签名与全部 exact binding，不打开 SQLite、不写文件。CLI 只返回 content-free digest/count/replay facts。`reconciliation_reviewed`
仍不授予 import、rollback、restart、SQL、Secret 解密或外部副作用 authority；任何领域 adapter 必须由下一份独立 ADR 定义。

验证结果：聚焦套件 `32 total / 30 pass / 2 conditional Docker skip / 0 fail`；完整 Local Owner
`254 total / 247 pass / 7 conditional skip / 0 fail`；tracked backend `1541 total / 1539 pass / 2 conditional skip / 0 fail`；
18-package clean build/逐包测试、八项架构/部署/发布审计、十四档 artifact audit 与真实 Docker readonly `2/2` 均通过。PostgreSQL 18.6
arm64 physical HA 以 146 gates、timeline `1 → 2` 通过，private report SHA-256 为
`3d6623465913d43e6f1a8838896d6deb6664dafd0c26970bddb4d6165fb60c00`，独立 evidence audit 无 finding。workspace 仍为 18 packages，
`singleSourcePackages=[]`、`shallowSourcePackages=[]`；Local Owner 为 `155 source / 154 nested / 1 root binary entry`，Local SQLite 为
`203 source / 202 nested / 1 root public export`。新增 7 个生产源码全部进入既有领域目录，没有新增 package、dependency、binary 或常驻
对象；基础 Edge/Standalone closure 精确保持 `2,611,978 / 2,612,056` bytes、319 files、58 modules。

## 被拒绝的替代方案

### 把对象名和冲突列表直接加入 plan

拒绝。会破坏内容无关 terminal evidence，使日志、Cluster consumer 和长期 receipt 获得敏感 inventory。

### 把 diagnostics page 当作 commit authority

拒绝。page 是 operator 工作材料，可能丢失、复制或被选择性展示；commit 必须从密封 bundle 重新派生完整 canonical fact sequence。

### 只依赖 `0600` decision file

拒绝。文件所有权只能证明 POSIX actor，不能证明近期强认证的人类 User，也不能抵抗 decision file 在签名前被替换。

### 在一个大 JSON 中加载全部诊断和决策

拒绝。会让路由器/NAS 内存随 schema 或 row 数增长，并产生超大临时字符串；page、NDJSON、hash 和比较都必须流式。

### 让人工批准直接调用通用 import

拒绝。八个领域的幂等键、Project/Policy、Secret custody、append-only history 和外部资产语义不同，不存在安全的通用回灌 SQL。

## 验收条件

1. 只有 exact `reconciliation_planned` plan/head 能建立唯一 review fence；restart、rollback、旧 plan 与第二 review 被阻断。
2. diagnostics page 固定最多 64 条，只写 owner-only no-replace 文件；stdout/content-free receipt 不泄漏路径、名称或 fact digest。
3. unknown/Secret/credential/pepper/active Run/hot journal 等 blocked facts 不能被人工选择提升为自动可处理。
4. Edge 8 MiB、Standalone 32 MiB private NDJSON 流逐条覆盖 required facts；缺失、额外、重复、乱序、替换和 digest drift 全部失败。
5. 只有近期强认证 User 可签发 authorization；credential/keyring/reviewer/file/plan/bundle/head 任一 fence 漂移时零 terminal publication。
6. authorization/review/receipt/head 的崩溃窗口和 response loss exact replay；verify 完全只读且不打开 SQLite。
7. review completion 无 SQL、DML、Secret 解密、checkpoint、service、Docker/init/network 副作用，也不授予 import/rollback/restart。
8. 无新增 package/dependency/常驻对象或根目录平铺；完整 Local Owner/backend/package、架构/release、十四档 artifact 和真实 Docker
   readonly rehearsal 通过，基础 Edge closure 不增长。

## 未包含

- 任一领域 adapter 的 SQL、文件转换、Secret re-encryption 或外部对象复制；
- 自动 import、Legacy overwrite、target restart、service cutover 或 reconciliation completion；
- Cluster/PostgreSQL/Kubernetes reconciliation；
- 强制双人审批、远程 KMS/HSM、网络签名服务或集中式审批 UI；
- 固定物理 Edge/NAS 的断电、FTL 写放大与介质销毁证明。