qinglong/docs/adr/ADR-0497-atomic-cluster-legacy-env-migration-application.md

# ADR-0497：Cluster Legacy Env 的原子 Task/Trigger 迁移与只追加回执

- 状态：Accepted
- 日期：2026-08-24
- 决策：D-402
- 关联：ADR-0104、ADR-0233、ADR-0259、ADR-0491、ADR-0495、ADR-0496

## 背景

ADR-0495 冻结了无敏感内容的 Cluster migration plan，ADR-0496 又让 Task 与执行修订只需保存
一个固定版本的 `environmentBundleRef`。此前仍缺少真正提交计划的 authority：如果分别调用现有
Task 与 Trigger repository，会开启两个独立事务，出现 Task 已改而 Trigger、schedule 或 receipt
尚未提交的裂脑窗口；如果一次把 100,000 个 Task 和 500,000 个 Trigger 全部装入 JS 数组，又会
让 Automation Manager 在低内存节点上不可用。

迁移还必须处理合法的历史 pin：Trigger 可能仍固定 Task r1，而 Task 当前 head 已推进到 r2。
新 Trigger 应固定本次迁移产生的 Task r3，不能错误假设旧 Trigger pin 等于 Task current head。

## 决策

### 1. 使用可重放流与双摘要冻结输入

新增 profile-neutral application contract 与
`qinglong/cluster-legacy-env-migration-application-receipt@v1`。调用方提供可重放的 Task/Trigger
mutation stream；每项包含 ordinal、实体身份、旧 revision/content digest 和独立 UUID mutation。
Task 与 Trigger 分别计算 source revision-set digest 和 mutation-set digest：前者必须匹配已发布
plan，后者必须匹配 application intent。

流必须从 ordinal 0 连续、按 Task/Trigger ID 严格递增，不允许重复、未知字段、非规范 UUID 或
超过 100,000/500,000 项。Task/Trigger ID 延续现有定义契约的 128-byte、无控制字符边界，不用
更窄的 ASCII 正则误伤合法历史数据。Trigger 可以为空，但 Task 至少一个。

### 2. 一个 Project-serialized SERIALIZABLE 事务完成全部写入

Automation Manager repository 先开启 `SERIALIZABLE`，取得 domain-separated Project advisory
transaction lock，再验证 active Project、plan ID/digest 和 exact mutation replay。每批最多只保留
128 项，先完整处理 Task，再处理 Trigger；任何流摘要、head、ownership、spec 或 CAS 不一致都会
回滚 receipt 和全部 revision DML。

Task 阶段对每个 current head 执行 `FOR UPDATE`，拒绝 Plugin-owned、非 `command@v1`、已有
`environmentBundleRef`、revision/digest 漂移和数据库时间倒退；新 revision 保留 name、description、
command config、labels、enabled 与 created time，只追加 plan 中的固定 bundle ref。enabled Task 同时
生成新的 `remote_worker` Cluster execution revision，数据库只保存 ref，不保存 Env 名称或值。

Trigger 阶段复验 current Trigger revision、旧 Task pin 和 schedule revision，保留 spec 与 enabled，
但绑定同 application 中该 Task 的新 revision/content digest。新 Trigger revision、head CAS 与
schedule reset 同事务提交；schedule 清空 due/claim 字段并递增 state/claim fence。旧 Trigger pin
可以是历史 revision，不要求等于 Task 迁移前 current head。

### 3. v70 提供三张只追加、无敏感内容的回执表

`pg-0071-cluster-legacy-env-migration-applications` 将 control contract 推进到 v70，新增：

- `cluster_legacy_env_migration_application_receipts`：application/plan/mutation、四个 set digest、
  固定 bundle ref、计数、数据库提交时间和精确 canonical receipt JSON；
- `cluster_legacy_env_migration_application_tasks`：每个 Task 的 before/after revision digest、mutation、
  可选 execution digest 和 item digest；
- `cluster_legacy_env_migration_application_triggers`：每个 Trigger 的 before/after revision、旧 Task pin、
  新 Task pin 和 item digest。

表中没有 Env name/value、bundle carrier、plaintext/ciphertext、key ID、Task/Trigger spec、命令或
provider path。application/plan/mutation/receipt 唯一，ordinal 与 revision 关系有 named constraints；
子表通过 `(application_id, project_id)` 复合外键隔离 Project，Trigger item 又通过复合外键固定到
同 application 的 Task item。三表均从 PUBLIC 撤销，只向 `ql3_automation_manager` 授予
`SELECT, INSERT`，不授予 UPDATE/DELETE/TRUNCATE。

### 4. Exact replay 不重新消费输入流

相同 application mutation 先读取 durable receipt，精确比较 intent，然后聚合验证 Task heads、
Task/execution revision、Trigger heads/revision 和 schedule 仍与逐项 receipt 一致。验证成功直接返回
`existing`，不调用 Task/Trigger stream factory；intent drift、receipt 缺项、ordinal gap 或 current
head 已继续推进均失败关闭。序列化、死锁和 lock timeout 使用新 stream factory 最多重试三次。

### 5. 不为该能力新增微包或 Edge 常驻成本

纯契约位于既有 `runtime-core` 的显式 subpath，PostgreSQL authority 位于既有
`cluster-postgres` 显式 subpath；不进入 runtime/admin/root entrypoint，不新增 workspace package、
生产依赖、daemon、controller、timer、watcher 或全集缓存。低内存 Cluster 节点只承担固定 128 项
batch；Edge/Standalone 默认 import graph 不加载 PostgreSQL authority。

## 被拒绝的替代方案

### 分别调用 Task 与 Trigger repository

拒绝。两个事务无法保证 Task、Trigger、schedule 和 receipt 原子，response loss 也无法证明哪一半
已经提交。

### 先收集全部候选再写数据库

拒绝。100,000/500,000 上限会把路由级设备或小型管理节点变成内存压力点；可重放有序流和固定 batch
已经能在事务回滚后重新计算摘要。

### 要求 Trigger 旧 Task pin 等于 Task current head

拒绝。不可变 Trigger 合法固定历史 Task revision；只需复验该旧 pin，并把新 Trigger 显式重定向到
本次 application 产生的新 Task revision。

### 把 Task/Trigger spec 或 Env 名称写进 receipt

拒绝。revision 本身已经保存规范 spec；receipt 只需要 identity、digest、count 和 fence，复制内容会
扩大 PostgreSQL backup、HA replica 和审计泄漏面。

## 当前验证与后续门禁

runtime-core 完整测试 `591/591`；cluster-postgres package 测试 `361 total / 358 pass / 3
conditional skip / 0 fail`；v70 migration/schema/readiness 定向门 `74/74`；CI 同构八角色
PostgreSQL integration `57/57`。Automation Manager 对 Project 与 immutable plan 只需普通
SERIALIZABLE `SELECT`，Task/Trigger 可变 head 与 schedule 继续持有 `FOR UPDATE`。真实 PostgreSQL
18.6 arm64 HA 多次通过 146 gates，timeline `1→2`；最终报告 SHA-256 为
`a7c8a05e08c748d677475a09ce2998b741ed9326e27678613e93d431bc3769aa`。

真实数据库用例证明：带空格的合法 Task/Trigger ID 可迁移；Trigger 固定 Task r1、Task current r2
时会原子生成 Task r3 与 Trigger r2 并让新 Trigger 固定 r3；execution plan 只出现 bundle ref；
schedule fence 递增且 claim/due 清空；exact replay 不消费 stream；Automation Manager UPDATE 以及
runtime/admin SELECT 均以 `42501` 被拒绝。

本 ADR 关闭 D-402 的 Cluster Task/Trigger application/receipt 边界，但 ADR-0491 仍保持 Proposed。
后续仍必须完成 direct Vault/KMS/HSM custody、migration Job 的短期身份与装配、在 PostgreSQL
promotion **之后**对既有 application receipt 执行 exact replay，以及固定低性能 Edge 设备的真实
空间、写放大、断电与恢复证据。