qinglong/docs/adr/ADR-0134-content-addressed-package-lock-and-recoverable-install-state.md

ADR-0134：内容寻址 PackageLock 与可恢复安装状态

• 状态：Accepted（OCI/offline 来源锁、digest-bound Approved Action、CAS 安装记录、 exact staging/activation receipt 和有界恢复判定已实现；ADR-0135 已补确定性签名 bundle 检查与 POSIX 私有 staging，ADR-0136/0137 已补 SQLite/PostgreSQL durable repository，ADR-0138 已补完整 lock 持久化、激活协调器与本地 pointer publisher； 原子资源 generation 发布与生产 composition 仍未开放）
• 日期：2026-07-24
• 关联 RFC：QL-RFC-0001 D-08、D-09、D-130、D-132

背景

ADR-0132 已能规范化 Package Manifest 并生成安装、升级和回滚预览，但预览本身不能 证明最终安装的仍是用户审批的字节。若后续安装器只保存 Package 名称和版本，会留下：

• OCI tag、URL 或本地路径在审批后改变；
• Manifest、解包内容和权限预览来自不同制品；
• upgrade 激活到一半时先撤销旧版本，重启后两代都不可用；
• activating 状态被盲重放，导致重复注册 Task、Tool 或 Trigger；
• SQLite 与 PostgreSQL adapter 各自发明状态和恢复语义；
• 低配设备为了尚未启用的安装器常驻 watcher、timer 或下载进程。

PackageLock 和安装状态机必须先成为 profile-neutral 领域契约，再允许文件、OCI、 SQLite、PostgreSQL 或 Kubernetes adapter 消费。

决策

1. 继续留在 @qinglong/runtime-core

新增 plugin-package-install subpath，不新增 workspace package或第三方依赖。它与 Manifest、Tool Registry 同属核心契约，但不读取文件、网络、数据库或环境，不拥有 下载、解包、动态 import、注册或执行能力。

禁用插件时现有 edge、standalone、cluster-control 和 worker composition root 不加载 安装 adapter，也不增加 timer、socket、连接或后台进程。

2. 来源只能是不可变内容地址

首版来源锁只接受：

• 带 exact @sha256:<64 hex> 的 canonical oci:// locator；
• 不保存主机路径的 offline:sha256:<64 hex> bundle identity。

两者都必须同时声明 1 byte–1 TiB 的 artifact 长度、artifact SHA-256 和解包后 content SHA-256；locator 中的 digest 必须与 artifact digest 相同。拒绝 tag、 latest、任意 HTTP URL、query、fragment、可变文件路径和 digest 不一致。

offline 只表达审批和审计中的来源身份，不授权打开任意路径。未来 POSIX adapter 必须另外取得私有文件 capability，且读取后复验 artifact/content digest。

3. PackageLock 精确绑定预览与已消费审批

PluginPackageLock 固定：

• Project、Package name/canonical SemVer、install/reinstall/upgrade/rollback；
• OCI/offline 来源、artifact/content digest 与字节数；
• normalized Manifest digest 和 compatible install plan digest；
• planner 使用的 QingLong/runtime/资源环境摘要，且 target 架构/Profile 必须一致；
• architecture、deployment Profile、target generation；
• upgrade/reinstall/rollback 的 previous lock digest；
• Approval request/version、immutable dispatch、human approver、有效期和 Project/RoleBinding fence；
• action、preview 与完整 lock digest。

action digest 覆盖所有可能改变安装结果的字段。Approval 的 action digest 必须与其 一致，preview digest 必须等于 install plan digest；PackageLock 只能在审批有效期内 创建，且安装记录必须在同一已消费审批有效期内建立。所有 Package 安装仍要求 user subject 的人工审批，Agent、MCP Client、API App 或 system 不能充当 approver。 构造 Lock 时必须用 exact environment 和 previous Manifest 重新执行 ADR-0132 planner，结果与传入 plan 摘要一致；不能把低风险伪 plan 与另一份 Manifest 分别摘要后一起锁定。

新安装只能使用 generation 1 且没有 previous lock；upgrade、reinstall 和 rollback 必须创建 generation 2+ 的新 lock，并绑定 previous lock。回滚不是把旧状态倒写， 而是以旧内容作为候选生成一个新的、可审计的 generation。

4. durable 状态机不拥有副作用

安装记录只有：

queued -> staged -> activating -> active
   |         |           |
   +---------+-----------+-> failed

• queued：PackageLock 与已消费审批已耐久保存；
• staged：artifact、Manifest 和 content digest 全部与 lock 相同，并保存摘要保护的 staging receipt；该 receipt 同时绑定 adapter 可重新检查的外部 evidence digest；
• activating：外部 adapter 可以开始原子发布，但 active pointer 仍指向旧 lock；
• active：只有绑定 installation、generation、previous pointer、stage 双证据和 content 的 exact activation intent receipt 提交后，active pointer 才切换到候选 lock；
• failed：保留失败阶段和受审 reason，active pointer 仍指向旧 lock。

首装失败时 active pointer 保持 null；升级或回滚失败时旧版本继续 active。终态不能 原地重试，必须创建新 mutation 或新 PackageLock，避免覆盖历史证据。

5. CAS、幂等与恢复必须显式

记录带单调 version、last mutation ID/digest 和 record digest。纯领域转换对最后一次 完全相同的 mutation 返回 existing 语义，同 ID 不同内容失败关闭。repository port 接收 expected version、expected record digest、mutation ID/digest 和完整 next record； adapter 必须以事务 CAS 和 mutation ledger 实现 exact replay，不能只做 last-write-wins。

恢复扫描每页最多 64 条：

• queued → resume_stage；
• staged → resume_activation；
• activating → inspect_activation；
• active | failed → none。

activating 只能检查外部 activation fact，再决定提交 receipt 或失败；禁止直接重放 发布。这与进程启动、Approved Action 和 PostgreSQL COMMIT-response-loss 的既有原则 一致：不确定结果先 inspect，不把异常冒充 rollback。

6. 本地协议闭环已可执行，但 production 仍 unreachable

ADR-0135 已实现 runtime-core 纯流式确定性 USTAR/Ed25519 检查器与 local-admin 私有 文件 staging adapter，但两个入口都是显式 subpath，未接入生产 composition。

ADR-0136 已实现本地 SQLite migration/schema/readiness、head CAS、mutation ledger 和 current-head recovery scan；ADR-0137 又以同一可执行合同完成 PostgreSQL migration/schema/admin-only repository parity。ADR-0138 进一步要求 queued record 与完整 PackageLock 原子保存，并实现了显式 fresh/recovery activation coordinator、 本地 POSIX pointer publisher 和注入 Approved Action consumer 的 SQLite 端到端组合。 这些能力仍只存在于按需 subpath。本 ADR 仍不实现：

• OCI client、publisher trust 获取/撤销和官方索引；
• 具体 Approved Action 产品 consumer、管理 API/CLI/UI 和 startup lifecycle；
• Task/Workflow/Prompt/Tool 的原子注册与旧 generation 退役；
• Kubernetes resource 或数据库 active generation publisher；
• production startup recovery coordinator 与 operator repair workflow；
• Trigger pause/health check、Runtime Extension 或动态代码加载。

在 adapter、Approved Action consumer、原子发布、Audit 和启动恢复闭环前，生产 composition 不得暴露安装入口。

影响

• 审批对象从“名称与版本”提升为 exact artifact、内容、Manifest、计划和目标环境。
• edge 可使用无路径的离线 bundle identity；cluster 可使用 exact OCI digest，二者共享 同一状态机。
• upgrade/rollback 不会在候选激活前移除旧 generation。
• packages/ 仍为 21 个 importer；ADR-0135 也只在既有 runtime-core/local-admin 增加按需 subpath。
• 该 contract 不是零闪存成本：加入 ADR-0138 的显式 activation/installation subpath 后最大制品为 2,825,780 bytes/437 files，最大单次 RSS delta 12,615,680 bytes， loaded module 数仍为 72，低于 4 MiB/512 files/16 MiB 硬门禁。
• SQLite/PostgreSQL adapter 已共用同一 CAS/receipt/recovery 可执行合同，后续变更 不能自行缩窄任一端安全语义。

验证

单元测试必须覆盖：

1. immutable OCI PackageLock 与 plan/approval digest binding；
2. 不保存主机路径的 offline bundle；
3. mutable source 与 source digest mismatch 拒绝；
4. detached、过期和非人工 Approval 拒绝；
5. exact environment/previous Manifest planner 重算与伪 plan 拒绝；
6. upgrade/rollback previous lock 与 generation 约束；
7. queued record 保留 previous active pointer；
8. exact staging receipt 与 lock mismatch 拒绝；
9. activating 阶段保持旧 active，commit 后才切换；
10. failure 保留旧 generation；
11. last mutation exact replay 与 mutation conflict；
12. 非法转换、时间倒退和 record tamper；
13. exact CAS commit envelope 与 immutable identity；
14. activating -> inspect_activation 及 64 条 recovery page 上限；
15. 根入口与 plugin-package-install subpath 导出一致。

ADR-0138 加入后当前针对性结果为 runtime-core 215/215、local-sqlite 68/68、 local-admin 50/50、cluster-postgres 非数据库全量 124 pass/1 skip，真实四角色 PostgreSQL 28 pass/1 skip。21 个 importer 的 clean build/聚合测试退出 0， dependency/source boundary 与 edge import 均通过且 findings=[]；六种 Profile artifact 全部通过，PostgreSQL 18 HA 的 21 个具体 gate 与总 passed 全为 true。