qinglong/docs/adr/ADR-0527-reviewed-automation-reconciliation-application-and-rollback.md

# ADR-0527：受审核 Automation Reconciliation 应用与显式回滚

- 状态：Accepted（源码与本地 exact arm64 演练已闭合；双架构阶段实物待交付）
- 日期：2026-09-01
- 决策：D-426c2
- 关联：ADR-0484、ADR-0485、ADR-0486、ADR-0487、ADR-0526

## 上下文

ADR-0526 已把 active target 的真实产品写入密封为独立 reconciliation capture，但 downloadable Trial Kit 仍停在 `review_required`。底层 plan、强认证 review、跨域 application plan、Automation row plan、apply 与 rollback 已存在；缺少的是一条部署者可执行、资源有界、不会自行替人决策的 exact artifact 链。

本切片只闭合一个最小可恢复事实：操作者审核完整计划并在 owner-private 文件中给出外部决定后，短生命周期 Operator 应用一个无冲突 Automation 行，验证正式 Task/Trigger 投影，再显式回滚到应用前 SQLite 快照。Secret/Config、Run History、completion 与服务重启继续留给后续独立决策。

## 决策

1. Trial Kit 新增 canonical `reconciliation-rehearsal.sh`，分为 `prepare`、`review`、`apply-rollback` 三个显式阶段。每个阶段只接受前一阶段的 exact sealed evidence，不跨阶段猜测路径、digest、时间或决定。
2. `prepare` 只从 ADR-0526 的 stopped capture 建立 bounded reconciliation plan、诊断页与强认证 review prepare，并终止于 `operator_decision_required`。`review` 只消费外部 review NDJSON，完成 authorization commit/verify、application prepare/commit/verify 与 Automation plan/verify，并终止于 `automation_decision_required`。`apply-rollback` 只消费外部 Automation row NDJSON，完成 decision commit、apply/verify、rollback/verify，终态为 `reconciliation_automation_rolled_back`。
3. 交付脚本永不生成 review 或 Automation decision。仓库中的 `ql3-local-alpha-reconciliation-decision-fixture.cjs` 只为 CI 合成数据生成冻结决定，不进入 Trial Kit、manifest、checksum 或用户下载包。Legacy Run History 固定为 `manual_external`，不能为了让演练通过而丢弃。
4. 每份外部 decision 必须是 owner-private canonical regular file：父目录为当前 UID 拥有的 `0700` 目录、目录中恰好只有该文件，文件不位于 deployment/reconciliation/capture 权威根内；容器只读挂载整个父目录。review 与 Automation decision 使用不同父目录，不能复用或替换。
5. review authorization 的有效期为 60 秒且不得晚于 strong principal；commit/verify 与 application/Automation 操作必须消费同一授权谱系。Automation decision commit 必须 `await` 完整确认后才能关闭 authentication database，避免异步确认读取已关闭 authority。
6. Automation target SQLite 必须位于 canonical deployment root 下，同时与 plan、capture、review、application、Automation 和 decision sibling roots 双向不重叠。apply/verify/rollback 使用短命名空间 `reconcile_automation_apply`，满足既有 32 字节授权上限。
7. `apply-rollback` 显式接收原始 Legacy root，并只读挂载它以复算 stopped proof；target deployment root 是唯一业务可写根。Operator 继续使用只读 rootfs、`network=none`、drop-all capabilities、no-new-privileges、128 MiB memory/swap、0.5 CPU、32 PID 与 8 MiB noexec tmpfs。
8. 所有带时间的 command 只在首次阶段创建；中断后必须复用原文件和原时间。容器输出先写 PID-scoped 临时结果，命令成功后才原子替换正式 result。失败重跑不能覆盖已存在的 authorization、intent、decision 或成功 result。
9. 成功 summary 只公开低敏 lineage：review/Automation/decision identity 与 digest、apply digest、采用的 Task/Trigger 数量、rollback head digest，以及 `target=restored_to_pre_automation_snapshot`。它固定 `completion=not_attempted`、`targetRestart=not_attempted`、`legacyRestart=not_attempted`。
10. Trial Kit、verification、offline audit 分别升级为 `@v10/@v8/@v7`，manifest schemaVersion 为 11；Local milestone 升级为 `@v6`、schemaVersion 6，并绑定双架构 `upgradeReconciliationRehearsalSha256`。required gate 新增 `legacyUpgradeReconciliationAutomationRollback=passed`，旧 bundle/milestone 不会被新 auditor 静默接受。

## Profile 与部署边界

- Edge/低配路由设备：默认 headless Application 和稳态资源不变。D-426c2 只启动串行短生命周期 Operator；不会新增 package、依赖、daemon、listener、timer、watcher、连接池或常驻缓存。
- Standalone：复用相同命令与安全边界，仅沿用既有较大 reconciliation 文件预算；本 ADR 不提高 Operator 资源上限。
- Console：同一 reconciliation script 可存在于 Console bundle，但不会启动 Web listener；3.0 Console 与 2.x 面板仍是不同 API/认证/领域协议，不能据此声明零改动兼容。
- Cluster：不复用 Local SQLite/POSIX/Docker 证据。PostgreSQL HA、Kubernetes lease、Worker 与 Cluster reconciliation 不受本 ADR 授权。

## 被拒绝的方案

- 在脚本内自动选择 `prefer_target` 或批量 adopt：会把 CI 策略伪装成人类审核，拒绝。
- 一次命令从 capture 直接推进 completion/restart：跨越 Secret/Config、Run History 与服务权威，拒绝。
- 只验证目标行数、不执行显式 rollback：无法证明应用前快照、backup digest 与恢复 head 闭合，拒绝。
- 把 decision 单文件直接 bind mount，或允许父目录中存在额外文件：会扩大路径替换与同目录注入面，拒绝。
- 为 Docker Desktop 放宽 POSIX owner 校验：会削弱原生 Linux 的 owner proof，拒绝。只读 readiness 可对瞬时 mount UID 漂移执行同一命令的一次有界重试；持续错误仍失败关闭。

## 验证与交付状态

- GitNexus 对修改的 TypeScript 符号均为 LOW：decision authorization 2 个上游、apply contract 8 个上游、apply/rollback authentication 4 个上游，均无 execution flow；shell 模板未被索引，按静态引用、`sh -n`、功能测试与 exact Docker gate 约束。
- 聚焦回归覆盖 strong-principal expiry、authentication database close fence、target path containment、短 authorization namespace、decision file private parent、命令/结果精确重放，以及 CI fixture 不进入 bundle。
- 本机完整 backend 回归为 `1667 total / 1665 pass / 0 fail / 2 conditional skip`；18 个 QL3 package clean build、package boundary、cluster dependency 与 image audit 均通过。PostgreSQL 18.6 arm64 HA Docker 门进一步完成 timeline `1→2` promotion 与 147 项检查，私有报告摘要为 `sha256:68e2f60b962ac62cee3c70bf759fccb6f8080541264427a4ea66bf8f586707db`。
- 本机 exact arm64 headless Trial Kit 使用最终 Application `sha256:eec404d24b5c101871e000caac902d3866e5fe3f0e6dcef31366cb526ef32f80` 与无源码覆盖的 Operator `sha256:10f75f12d185e5796dcc4a230b6684c074bd9a6e6156ee1110fff1c2d8dd3390`，离线 audit v7 返回 `compatible=true`。全新 2.x fixture 已贯通 readiness、stage、cutover、post-write capture、437 条外部 review 决定、1 条外部 Automation 决定、apply/verify 与 explicit rollback/verify；最终实际采用 1 个 Task、1 个 Trigger并返回 `reconciliation_automation_rolled_back`，且未尝试 completion、restart、Secret/Config 或 Run History mutation。
- 该本机证据是工程闭合，不冒充 GitHub workflow provenance 或双架构阶段实物。只有普通 CI、Kubernetes/Cluster 门与显式 amd64/arm64 artifact finalizer 全部成功后，D-426c2 才升级为可下载阶段产物。

## 后续

D-426c3 再独立处理 Secret/Config、Run History、跨域 completion 与 target/Legacy restart 选择。2.x 面板复用走单独 UI adapter RFC：保留现有视觉组件，替换 `/api/*` 数据层、JWT/session 假设与 Crontab/Env/Log 领域映射；不得把 D-426c2 当作 2.x API compatibility layer。