qinglong/docs/adr/ADR-0138-durable-plugin-package-lock-and-exact-local-activation.md

# ADR-0138：耐久 Plugin Package Lock 与精确本地激活

- 状态：Accepted（完整 PackageLock 原子持久化、双 staging evidence、activation intent、
  fresh/recovery coordinator、本地 POSIX publisher、SQLite 端到端组合与 PostgreSQL
  四角色持久化验证已完成；ADR-0139 已补 Cluster publisher，ADR-0140 已补调用方驱动
  启动恢复、本机 application gate、标准 OCI resolver、Cluster admin process、
  独立镜像与 Job/RBAC；ADR-0149 已补原子资源 generation identity/source，具体语义
  materializer 与私有 registry 仍未开放）
- 日期：2026-07-24
- 关联 RFC：QL-RFC-0001 D-08、D-09、D-132 至 D-136
- 关联 ADR：ADR-0087、ADR-0134、ADR-0135、ADR-0136、ADR-0137

## 背景

ADR-0134 至 ADR-0137 已冻结 PackageLock、安装状态机、确定性 staging 和两种数据库
Repository，但实现审计发现三个不能留给产品层修补的缺口：

1. Repository 只保存 record JSON 与 lock digest。进程重启虽能判断
   `resume_stage | resume_activation | inspect_activation`，却无法重建被审批的完整
   PackageLock；
2. POSIX staging adapter 返回 `receipt.json` 的真实 SHA-256，而领域
   `stage_completed` 又生成另一个 receipt digest。后者没有保存前者，激活时无法证明
   正在发布的仍是已验签、已 fsync 的字节；
3. activation receipt 只绑定 generation 和 content。相同 generation/content 可在不同
   installation 或不同 previous pointer 之间误重放；`activating` 的 fresh publish、
   response-loss 和 restart recovery 也没有唯一协调器。

这些问题在低配路由设备上不能靠常驻 watcher 或额外数据库解决，在 Cluster 多副本上
更不能靠进程内锁解决。修复必须继续服从 ADR-0087：能力应优先成为现有包的显式
subpath，不能因为一个 adapter 或 coordinator 再创建单文件 workspace package。

## 决策

### 1. 完整 PackageLock 与 queued record 原子保存

`PluginPackageInstallCreate` 必须携带规范化后的完整 PackageLock。Repository create
在同一个数据库 transaction 中保存 lock 与 queued record，并逐项复验
installation、Project、Package、generation、previous active pointer 和 lock digest。

Repository port 新增 `findLock(lockDigest)`。读取必须重新运行 PackageLock normalizer、
重算 digest，并拒绝 JSON、索引列或 record 之间的任何漂移；未知 digest 返回 null，
corrupt durable fact 返回 unavailable。

- SQLite `0037` 使用 `lock_json TEXT NOT NULL`，CHECK 固定 JSON object、lock digest、
  Project 和 Package；
- PostgreSQL `pg-0018` 使用 `lock_json jsonb NOT NULL`，除同样绑定外还限制 JSON
  object 和大小；
- 两种 adapter 继续由同一 shared repository contract 驱动。

不单建 lock 表：PackageLock 与 installation 同生且不可变，一对一列存储能在不增加
join、表、migration version 或 importer 的前提下保持事务原子性。

### 2. staging 同时保存领域回执和外部字节证据

`PluginPackageStageReceipt` 增加 `evidenceDigest`。领域 receipt digest 继续绑定
lock、artifact、Manifest、content 和 stage reference；`evidenceDigest` 则精确保存
adapter 可重新检查的外部事实：

- 本地 staging 为 canonical `receipt.json` 原始字节的 SHA-256；
- 未来 OCI/Kubernetes adapter 必须提供同等不可变、可 inspect 的证据摘要。

激活 publisher 必须同时检查领域 stage receipt 和外部 evidence，不能把“状态机曾进入
staged”当作“当前落盘字节仍可信”。

### 3. activation intent 绑定完整切换事实

ADR-0149 将其升级为 `qinglong/plugin-package-activation-intent@v2`，除下列切换事实外
还完整携带并摘要绑定受限的 resource generation：

- installation、Project、Package 和 PackageLock；
- target generation 与 exact previous active lock；
- stage reference、领域 stage receipt digest、外部 evidence digest；
- content digest 与 domain-separated intent digest。

activation receipt 必须携带并匹配 intent digest。这样即使 content 和 generation
相同，也不能跨 installation、Project/Package、previous pointer 或 stage evidence
重放。

### 4. fresh publish 与 recovery inspect 严格分离

`PluginPackageActivationCoordinator` 只有两条路径：

- fresh：先 CAS 保存 `activating`，再调用 publisher `publish`；得到 exact receipt 后
  才 CAS `active`；
- recovery：只调用 publisher `inspect`。exact published fact 提交 `active`，
  `not_published` 提交受审 failure，冲突提交 `activation_fact_conflict`。

publish 抛出 availability 或响应丢失时，durable record 保持 `activating`，调用者不得
在同一不确定路径重新 publish。terminal exact retry 只返回已保存事实。

`PluginPackageInstallationCoordinator` 固定
Approved Action consume → durable create/findLock → stage → staged CAS → activation
coordinator 的顺序。Approved Action consumer 是必须由产品层提供的受信、exact-replay、
带 fence capability；当前不提供默认或弱化实现。

### 5. 本地 publisher 使用单一私有原子 pointer

`@qinglong/local-admin/package-activation` 只接受两个预创建、当前 UID 拥有、真实
`0700` 且 device/inode 稳定的独立目录。每次 inspect/publish 都重新验证 authority，
再逐项验证 staging receipt、blob exact set、owner、mode、size 和 digest。

active pointer 名称由 Project/Package 的 domain-separated SHA-256 派生，内容为
canonical intent + receipt，权限固定 `0600`。ADR-0149 将 pointer 升级为 v2，使资源
generation 与 package pointer 同一次 rename 生效。publication 使用：

1. per-pointer `O_CREAT | O_EXCL | O_NOFOLLOW` 的 `0600` 锁；
2. 写入并 fsync 私有临时文件；
3. 同目录 atomic rename；
4. fsync activation directory；
5. 重新 inspect 最终 pointer。

升级必须匹配 exact previous pointer；stale writer 冲突失败关闭。publisher 记录自己
创建的锁 inode/device，finally 只删除身份仍匹配的 owned lock；若另一 publisher 已持锁
或路径被替换，绝不按文件名删除。

### 6. 组合继续留在既有包

- runtime-core 增加显式 `plugin-package-activation` 与
  `plugin-package-installation` subpath；
- local-admin 增加显式 `package-activation` 与 `package-installation` subpath；
- local-sqlite、cluster-postgres 只扩充原 repository subpath；
- 不新增 workspace package、第三方依赖、timer、watcher、socket、sidecar 或数据库
  connection。

本地组合已用 SQLite Repository、真实 staging evidence 和 POSIX publisher 完成端到端
测试，但没有从 package root 或 production application root 导出。

### 7. Cluster 恢复已组合，产品安装入口继续失败关闭

ADR-0140 已把 allowlisted OCI source resolver、可选 exact-registry credential
provider、同一 PostgreSQL lock authority 驱动的 stage verifier、独立 cluster-admin
image 与最小权限 Job/RBAC 组合完成。
它仍不开放：

- 具体 Approved Action durable consumer、管理 API/CLI/UI；
- operator repair workflow；
- ADR-0149 已完成的原子 generation identity/source 之上的
  Task/Workflow/Prompt/Tool/Trigger 语义 materializer 与旧代 GC；
- object-store stage；
- publisher revoke/index、Runtime/UI Extension 或动态代码加载。

因此“本地端到端组合可执行”不等于 QingLong 3.0 已允许用户安装插件；生产入口必须等
上述 authority、Audit、recovery 与资源语义 materializer 闭环完成后另行评审。

## 拒绝的方案

- 为 activation、installation coordinator 或每种 publisher 各建 workspace package：
  拒绝；这些边界由 subpath 和 dependency audit 足以隔离，拆包只增加 importer、
  build、发布和路由设备安装元数据成本。
- 只保存 lock digest，恢复时从 OCI/tag/文件重新生成 lock：拒绝；来源可能不可用，
  也无法重建已消费审批和当时环境。
- staging receipt 只保存领域摘要：拒绝；无法复验 adapter 已落盘的具体字节。
- `activating` 重启后再次 publish：拒绝；响应丢失时会重复外部副作用。
- 用无条件 `unlink(lockPath)` 清理竞争锁：拒绝；文件名不证明所有权。
- 让 local-admin 默认创建 Approved Action consumer：拒绝；会绕过身份、Policy、
  Approval ledger 和 Audit 的产品 ceremony。

## 影响

- edge/standalone 仍使用单 SQLite authority、短 transaction 和调用时 I/O；禁用路径
  不加载安装/激活 subpath，常驻成本不增加。
- Cluster Repository 已能耐久恢复完整 lock，ADR-0139 也已提供 ConfigMap publisher；
  stage verifier、短生命周期 process 和 RBAC 已组合；ADR-0149 已组合原子 resource
  generation identity/source，但语义 materializer 与 Approved Action 产品入口仍未
  组合，默认控制面仍不可安装 Package。
- 两个方言和未来 publisher 共用同一 intent/recovery 语义；数据库与部署差异留在
  adapter。
- workspace importer 保持 21 个；本切片没有新增 package 或第三方 dependency，回应
  “packages 是否拆得过细”的原则是：单文件能力先并入职责相符的包并用显式 subpath
  隔离，只有出现独立发布、独立运行或真正不同依赖生命周期时才考虑拆包。

## 验证

必须覆盖：

1. SQLite/PostgreSQL lock 与 record 原子保存、`findLock` exact replay 和 corruption；
2. shared repository contract 的缺失 lock、head replacement、CAS 和 recovery page；
3. staging 外部 evidence 进入 durable receipt 并参与 activation intent；
4. fresh activation 在 publish 前已保存 `activating`；
5. publish response loss 后只 inspect、不重复 publish；
6. external fact absent/conflict 的稳定 failed reason；
7. 本地 pointer exact replay 不推进时钟；
8. previous pointer replacement 和 stale writer conflict；
9. stage blob、receipt、pointer、root/symlink tamper fail-closed；
10. 预先存在的另一 publisher lock 不被删除；
11. Approved Action → SQLite lock → stage → POSIX active 的端到端组合；
12. explicit subpath/root isolation、依赖方向、六 Profile artifact 与 edge import；
13. PostgreSQL 四角色最小权限与物理 HA。

当前针对性结果为 runtime-core 224/224、local-sqlite 68/68、local-admin 51/51、
cluster-postgres 非数据库 124 pass/1 条件 skip，以及 PostgreSQL 18 四角色真实集成
28 pass/1 条件 skip。21-package clean build/聚合测试退出 0；dependency/source
boundary 与 edge import 通过且 `findings=[]`；ADR-0140 production wiring 后六种
Profile 全部通过，最小 Profile 仍为 39 loaded modules，最大 application 为
2,849,491 bytes/439 files/78 loaded modules，最大 RSS delta 13,090,816 bytes；
PostgreSQL 18 HA 的 21 个具体 gate 与总 `passed` 全为 true。