qinglong/docs/adr/ADR-0065-durable-local-application-cutover-supervisor.md

# ADR-0065：持久化本机应用切换 Supervisor 与未知结果收敛

- 状态：Superseded（ADR-0243；未接入产品的 package 实现已删除）
- 日期：2026-07-20
- 关联 RFC：QL-RFC-0001 D-05、D-17、D-37、D-40、D-42、D-63、D-64、D-65
- 关联 ADR：ADR-0004、ADR-0007、ADR-0036、ADR-0062、ADR-0063、ADR-0064、ADR-0066

> ADR-0243 已删除 `@qinglong/local-cutover` 的孤立孵化实现。本 ADR 保留为 cutover
> 安全语义记录，不代表当前仓库仍提供 Supervisor package。ADR-0309 已在现有
> `ql3-local-deploy` 产品中恢复 Docker legacy-stop journal/commitment 与 adopted v3
> 启动门；ADR-0310 又恢复 Docker target start/restart barrier、崩溃后 inspect-only
> 与 terminal `manual_required`。ADR-0313 已恢复人工 resolution，ADR-0314 已恢复 Docker target
> stop 和最小写后分类；其他 init controller、legacy restart 与数据域回退仍未实现。

## 上下文

ADR-0064 已能在数据库层证明 source 与 recovery 一致、在双库写栅栏内签发 activation，并在 adopted storage 生命周期内阻断旧 SQLite writer。但数据库锁不能证明旧 HTTP listener、timer、子进程、通知请求或其他外部副作用已经停止，也不能覆盖“停止 2.x 后进程崩溃”“target start 已发出但结果未落盘”“target 曾 active、控制进程重启后 2.x 被人工拉起”等窗口。

若把这些步骤直接写入 legacy `back/app.ts`，2.x 根应用会重新成为 3.0 的进程管理 authority；若只用内存布尔值或 shell 命令串联，控制进程崩溃后无法判断某个 start 是否已经产生副作用。最危险的错误恢复是同时重启 2.x 和 3.0，或者在未知 start 结果上再次 start。

## 决策

### 1. Cutover 是独立、默认关闭的部署 authority

新增 `@qinglong/local-cutover`，只提供 driver-neutral 的切换 contract、Supervisor 和文件 journal adapter。它没有 production dependency，不导入 legacy 根、local-admin、local-sqlite、local-adopted-profile、cluster、Worker、Express、Sequelize 或 Drizzle，也不自行注册 timer、watcher、signal handler、listener 或数据库连接。

当前所有既有 runtime/Profile package 都禁止反向导入该 authority。后续只能由独立部署入口显式组合具体 2.x process controller 与 3.0 target controller；不得把它塞回普通应用启动路径。

disabled 路径在验证 cutover ID、activation digest、journal 路径或 controller 前返回，不触碰文件和进程。

### 2. Process controller 必须返回绑定切换身份的证明

Supervisor 不接受一个裸 `stop` exit code。legacy controller 的 exact-shape evidence 必须同时绑定 `cutoverId`、`activationDigest`、controller identity、稳定 process identity、观察时间，并明确声明：

- database writer 已停止；
- application 外部副作用已 quiesced。

target start/inspect/stop evidence 同样绑定 cutover 与 activation，并包含 controller/target identity。畸形、可扩展、跨 cutover 重放或身份漂移全部 fail closed。这里的 controller 是部署信任边界；当前 package 只验证 evidence contract，不假装能从 PID 或 SQLite 锁独立推导网络、子进程和外部系统已经静默。

### 3. 每个状态转换先进入有界、不可覆盖的 durable journal

journal 位于操作员预先创建的绝对路径私有目录，要求真实目录、当前用户所有且 group/other 权限为零。每条记录：

- 使用连续十二位序号和 `0600` regular file；
- 绑定 cutover/profile/activation、前一条 digest、状态、时间和低敏 evidence；
- 通过 SHA-256 形成不可变链；
- 最多 64 条记录、128 个目录项和 64 KiB 单记录；
- 先写同目录私有临时 inode 并 `fsync`，再用 no-overwrite hard link 原子发布，最后同步目录；
- 同一 sequence 的并发 compare-and-append 只能有一个 winner。

未知文件、symlink、权限过宽、序号空洞、非法 transition、digest/evidence 漂移或资源超限均 fail closed。journal 只保存低敏 identity/digest，不持久化原始错误文本、token、数据库 URL 或 Secret。

### 4. 首次切换必须先证明 legacy 停止，再跨 target start barrier

正常序列固定为：

```text
requested
  -> legacy_stop_requested
  -> legacy_stopped
  -> target_start_requested
  -> target_active
```

`legacy_stop_requested` 可在崩溃后幂等重做 stop-and-verify，因为它只收敛旧 owner。`target_start_requested` 是外部副作用 start barrier：同一调用在 barrier 持久化后只调用一次 `startAndVerify`；若控制进程在调用期间崩溃，恢复只能 `inspect`。只有 exact active evidence 可以补写 `target_active`；inactive、unknown、异常或不匹配都进入 terminal `manual_required`，禁止盲目再次 start，也禁止自动重启 legacy。

### 5. Target 重启前必须重新证明 legacy 仍静默

曾经 `target_active` 的 journal 不代表旧进程永远停止。若恢复时 target inspection 为 inactive，必须执行：

```text
target_active
  -> legacy_recheck_requested
  -> legacy_reverified
  -> target_restart_requested
  -> target_active
```

只有新的 legacy evidence 同时证明数据库 writer 与外部副作用仍停止，才允许写 restart barrier。`target_restart_requested` 与首次 start barrier 相同：崩溃恢复只 inspect，不重放 start。target inspection 为 active 时还必须与已记录 controller/target identity 一致；unknown 或 identity drift 进入人工恢复。

target 正常停止使用 `target_stop_requested -> stopped`，stop-and-verify 可以幂等恢复。停止 target 后 Supervisor 不自动重启 2.x，因为 target 可能已经产生 3.0 新事实；回退仍遵守 ADR-0064 的 reconciliation 边界。

### 6. `manual_required` 是安全终态，不是可重试错误

legacy 停止未证明、target start/restart 结果未知、active identity 漂移、target stop 未证明或 journal fencing 冲突都必须收敛为 `manual_required`。记录只包含有限 reason、uncertain state 和错误摘要 digest。

同一 cutover ID 不允许从 `manual_required` 或 `stopped` 自动重新开始。操作员必须先检查进程、外部副作用、activation 和 target 数据事实，再通过后续受审恢复命令创建新的 cutover/recovery 事实；不得删除或重写旧 journal 伪造新起点。

## 被否决的替代方案

1. **在 `back/app.ts` 内直接 stop 旧 runtime 并启动 3.0**：继续让 legacy 根成为新架构 service locator，且进程崩溃后没有独立权威，拒绝。
2. **只检查 PID 不存在**：PID 可复用，且不能证明子进程、listener 或远端副作用静默，拒绝。
3. **target start 报错就自动重试**：错误可能发生在副作用之后，会形成重复 owner，拒绝。
4. **target 启动失败就自动重启 legacy**：未知 target 可能已经 active，且 target 可能已有新事实，会造成双跑或数据丢失，拒绝。
5. **用一个可覆盖 JSON 保存当前状态**：断电、并发 writer 或部分写会丢失转换历史和 CAS fence，拒绝。
6. **target 曾 active 后直接按旧 legacy evidence 重启**：旧证据可能已因人工恢复失效，拒绝；必须重新 stop-and-verify。

## 影响与未完成项

正向影响：

- 数据库 activation 与应用进程 cutover 成为两个清晰 authority；
- start/restart/stop 崩溃窗口有 durable barrier，不靠内存猜测；
- 并发 supervisor、journal 篡改和错误详情泄漏均 fail closed；
- edge 不安装进程管理 framework 或 cluster 依赖；
- 旧应用不会因 target 错误被自动拉起形成双 owner。

仍未完成：

- systemd、Docker/s6 与当前 QingLong master/worker 的具体 legacy controller；
- 把具体 Run/scheduler/Executor recovery、lifecycle 和 admission stack 注入 local-application，并由独立 target process controller 驱动；
- `manual_required` 的只读诊断、人工 resolution 和新 cutover ceremony；
- 多资产 backup manifest、target 写后 reconciliation 和用户可见回退选择；
- Linux x64/arm64、固定路由设备、断电和只读/overlay 文件系统验证；
- 独立 supervisor CLI/镜像、权限模型、SBOM、签名与审计导出。

因此本 ADR 只把 cutover state machine 和 crash semantics 孵化为默认不可达的 authority，不表示 QingLong 3.0 已自动接管 2.x 部署。

## 验证

1. disabled 路径不读取 journal、不调用任何 controller。
2. 正常流程严格先持久化 legacy stop proof 和 target start barrier，stop 后不启动 legacy。
3. legacy evidence 不完整时 target 永远不启动并进入 `manual_required`。
4. start barrier 后的异常不保存原始错误、不重放 start；重入保持同一人工终态。
5. start crash 只有 exact active inspection 能恢复，inactive/unknown 不会重试。
6. 曾 active 的 target 只有在新 legacy quiescence evidence 后才能重启。
7. stop crash 只幂等 stop-and-verify，不会触发 legacy start。
8. 两个并发 first append 只有一个成功；篡改、宽权限和 symlink journal 均 fail closed。
9. package dependency/import audit 证明 local-cutover 没有 runtime dependency，且既有 package 无法反向导入。
10. supervisor、真实 target/legacy adapter、写后 reconciliation 和多架构 Gate 完成前保持默认不可达。