mirror of
https://github.com/whyour/qinglong.git
synced 2026-09-21 00:38:14 +08:00
feat(ql3): qualify plugin upgrades before activation
This commit is contained in:
whyour
@@ -34,6 +34,7 @@
|
||||
- 真实 K3s `v1.34.3+k3s1` 已完成 admission 编译与现场门：合规 Job 的 server dry-run 通过，篡改镜像被策略拒绝，删除参数 ConfigMap 后创建被拒绝；controller SA 的 `list|watch|delete jobs`、Pod 创建和 Secret 读取均被拒绝，action SA 的 Job/Pod 创建与 Secret 读取也均被拒绝。实现仍保持 18 个 package，未新增 workspace package、Edge daemon/timer/watcher 或低配设备常驻负担；短生命周期 controller 与按需 action Job 仅属于 Cluster profile。完整 18-package clean build/test 退出 0；backend 1196 项为 1194 pass、2 条条件 skip、0 fail；cluster-admin 339 pass/3 skip、cluster-postgres 328 pass/2 skip，package boundary、cluster dependency、edge import 和 cluster deployment 审计均无 finding。PostgreSQL `18.4` arm64 physical HA 125 项、timeline `1→2` 通过，报告 SHA-256 为 `a3d34e61ea2064e1cde574e533137186e09fdce9048455da64f582906037fa0d`，临时 Docker 资源已清理。ADR 仍为 Proposed：升级失败自动回滚、终态 Job 的 durable 恢复决议和固定物理低配设备证据尚未完成。
|
||||
- 2026-08-14 终态恢复更新：Secret Action controller 不再把所有终态 Job 仅计为瞬时 `recoveryRequired`。Job 到达 Complete/Failed 后已停止执行，controller 会用 started execution 的原 lease fence 复验不可变业务结果：首次 binding 必须与 approval plan、`startedAtMs` 推导出的 binding 完全一致；transition 必须与 plan、authority evidence、commit time 推导出的 receipt 完全一致。精确 durable result 存在时补写 `succeeded`，即使 Job 已被 TTL 清理也能收敛；Failed 且无 durable mutation 时写 `failed`；Complete 但无 receipt 时以 `indeterminate` 写 `blocked`。Job 在 start barrier 前终态或审批过期且尚未创建时，controller 复用既有 claim→release fence 写 `blocked`，不让坏 Job 永久占据 reconciler 页首。任何 stored result 漂移继续抛出 conflict，`executing + Job 缺失 + receipt 缺失` 继续要求人工处理，绝不自动重建可能已产生副作用的动作。该切片不修改共享 execution schema、PostgreSQL migration 或角色权限，不新增 package、连接与常驻进程；Cluster controller 复用现有 package-executor Pool，Edge 零变化。controller/process 定向 21/21，cluster-admin 全包 348 项为 345 pass/3 条件 skip/0 fail；完整 18-package 串行 build/test 退出 0；backend 1196 项为 1194 pass/2 条件 skip/0 fail；package boundary、cluster dependency、edge import、cluster deployment 均无 finding，部署/包边界聚焦测试 61/61。PostgreSQL `18.4` arm64 physical HA 125 项、timeline `1→2` 通过，报告 SHA-256 为 `bec512767fbbd7774baa9366698f60c25c8b017ed66f459b154d143fe86293bc`，临时 Docker 资源已清理。
|
||||
- 2026-08-14 人工恢复更新（ADR-0397，已接受）：上述唯一保留的 `executing + Job/receipt 均缺失` 不确定窗口现在具有显式 Cluster 产品处置路径。既有 Approval management mTLS/OIDC endpoint 新增 `approval.recover.inspect|resolve`，只接受五分钟内 `multi_factor|hardware` User、独立 `approval.recover` 权限、二次认证、exact execution version/digest 和外部 evidence SHA-256。只允许 Secret binding/transition action；`confirm_failed` 写 failed，`abandon_unknown` 写 blocked，永远禁止人工 succeeded、Job 重建或 execution 重置。PostgreSQL `pg-0065`/capability v64 新增不可变 resolution ledger 与单个 SECURITY DEFINER resolver，在同一事务内锁 Policy/execution fence、写 allowed audit、推进终态并写 receipt；Approval manager 只有 dispatch/execution/resolution SELECT 与函数 EXECUTE，没有 execution UPDATE。通用 execution repository 与 Worker Credential 调用链保持不变。真实 PostgreSQL 18.4 已从空库完成 65 migration，证明原子提交、exact replay 不重复审计和 direct UPDATE `42501`；实现不新增 package、依赖、Pod、Pool、daemon、timer、watcher 或 Edge/Standalone 负担。18-package clean build/test 退出 0，backend 1,194 pass/2 skip/0 fail，package/dependency/edge/deployment 审计零 finding；新 migration 与 repository 内聚到 `approved-action` 领域，migration ledger 直属源码保持审定上限 65。PostgreSQL 18.4 arm64 physical HA 125 项 gate、timeline `1→2` 通过，报告 SHA-256 为 `6d4921cba74475d15722a13c6a8034793c0ee25681bc7dcaf91024927c5752fe`，临时 Docker 资源已清理。
|
||||
- 2026-08-14 升级失败收口（ADR-0398，进行中）：已存在旧 active 的 `upgrade|reinstall|rollback` 不再先切 active pointer 再物化 Package 资源。共享 activation prerequisite sequence 固定为 Secret binding/transition receipt 就绪后，从 staged install 与 immutable lock 构建候选 generation，按既有字节上限完成 Manifest、Task、Workflow、Prompt、Tool 语义物化，并以 generation digest 预发布 immutable revision；只有成功后才进入 active pointer CAS。确定性候选错误把本次 install 写为 `failed(activation_fact_conflict)`，`activeLockDigest` 保持 `previousActiveLockDigest` 且 publisher 不被调用；瞬时文件/OCI/数据库故障保持 staged 重试。generation 1 没有旧版本可保留，Secret-aware 首次安装继续使用 ADR-0395 的 post-activation B1 binding ceremony，不被候选门错误拒绝。激活后的 publication recovery 只复用 revision 做 generation-fenced reconciliation。实现复用既有 18 个 package、双方言 repository、Local 单 SQLite authority 与 Cluster caller-driven recovery Job/单 Pool，不新增 migration、表、依赖、daemon、timer、watcher、listener、连接池或常驻 cache。定向 Runtime Core 21/21、Runtime Core 全量 548/548、Local Application 47 pass/4 条件 skip、Cluster Admin 347 pass/3 条件 skip；18-package clean build/test 退出 0，backend 1196 项为 1194 pass/2 条件 skip/0 fail，package boundary、cluster dependency、cluster deployment 与 edge import 审计均通过。PostgreSQL `18.4` arm64 physical HA 125 项、timeline `1→2` 通过，报告 SHA-256 `75d7a52be75c22b2aacf32f2d7e2c432a467ebaab4d639668ff3a4b98767a17e`。真实 Kubernetes 失败升级未移动 active pointer/head 的现场门与固定物理低配设备证据仍待闭合。
|
||||
- D-302/ADR-0390（已接受）
|
||||
Cluster operator context 增加无网络、无 mutation 的内建 `ql3-cluster-admin context validate` 预检。它先复用 owner-private context
|
||||
reader，再让每个 entry 经过与真实请求相同的 production HTTPS/Kubernetes configuration preparation，验证精确 route、hostname、CA、
|
||||
|
||||
@@ -51,3 +51,8 @@ D-306B1 只允许给当前 active 且尚未绑定的 Package generation 做首
|
||||
- start barrier 前的终态 Job、以及 approval 过期且 Job 尚未创建，复用共享 execution repository 的 claim→release-before-start 转换持久化为 `blocked`；controller 崩溃后 lease 可回收，不增加新状态、表、migration 或专用恢复 daemon。Durable result 漂移仍是全局 conflict；`executing + Job 缺失 + receipt 缺失` 不能排除孤儿 Pod 或未知副作用，继续保持 `recoveryRequired` 且绝不重建。
|
||||
- 本切片定向 controller/process 21/21；cluster-admin 全包 348 项为 345 pass、3 条件 skip、0 fail；完整 18-package 串行 build/test 退出 0；backend 1196 项为 1194 pass、2 条件 skip、0 fail；package boundary、cluster dependency、edge import、cluster deployment 均无 finding，部署/包边界聚焦测试 61/61。PostgreSQL `18.4` arm64 physical HA 125 项、timeline `1→2` 通过，报告 SHA-256 `bec512767fbbd7774baa9366698f60c25c8b017ed66f459b154d143fe86293bc`，临时 Docker 资源已清理。共享 `approved_action_executions` contract、PostgreSQL 权限与 Worker Credential 调用链均未修改；实现继续位于既有 `cluster-admin/plugin-package/executor`，Edge/Standalone 不加载 controller，也没有新增 workspace package、连接、timer、watcher 或常驻内存。
|
||||
- ADR 继续保持 Proposed：升级失败自动回滚、`executing + Job/receipt 均缺失` 的显式人工处置产品路径，以及固定物理低配设备证据仍待完成。
|
||||
- 后续 ADR-0397 已完成上述 Secret Action 显式人工处置。ADR-0398 进一步把 Local/Cluster 安装恢复顺序改为“Secret transition prerequisite → staged candidate materialization/publish → active pointer CAS → active-only reconciliation”。确定性候选错误在 pointer 发布前把当前安装写为 failed，`activeLockDigest` 保持上一 lock，旧 generation/binding/revision 继续服务；可用性错误只重试。该实现不新增 package、migration、连接或常驻组件。
|
||||
- ADR-0398 的 18-package clean build/test、backend、边界/依赖/部署/edge import 审计与 PostgreSQL
|
||||
`18.4` arm64 physical HA 已闭合；HA 通过 125 项门、timeline `1→2`，报告 SHA-256
|
||||
`75d7a52be75c22b2aacf32f2d7e2c432a467ebaab4d639668ff3a4b98767a17e`。真实 Kubernetes
|
||||
失败升级未移动 active pointer/head 的现场门与固定物理低配设备证据仍阻断 ADR Accepted。
|
||||
|
||||
@@ -0,0 +1,75 @@
|
||||
# ADR-0398：Plugin Package 激活前候选资格校验与自动保留旧版本
|
||||
|
||||
- 状态：Proposed
|
||||
- 日期：2026-08-14
|
||||
- 关联 RFC：QL-RFC-0001 D-306B2
|
||||
- 关联 ADR：ADR-0153、ADR-0394、ADR-0396
|
||||
|
||||
## 问题
|
||||
|
||||
现有 Local 与 Cluster 启动恢复先发布 active pointer、把安装记录推进为
|
||||
`active`，随后才读取 staged bytes、物化 Package Task/Workflow/Prompt/Tool 资源。
|
||||
因此一个摘要正确但资源语义无效的升级可能先替换健康版本，再在任务发布阶段失败，
|
||||
迫使整个启动门失败。安装状态机虽然保留 `previousActiveLockDigest`，却没有在指针切换前
|
||||
使用该事实形成真正的失败隔离。
|
||||
|
||||
“先切换、失败后再把指针写回去”也不安全：回写会与并发发布竞争，Kubernetes
|
||||
ConfigMap 和数据库 head 之间会出现第二次分布式提交窗口，并且历史 generation 可能被
|
||||
静默重新激活。自动恢复应避免制造需要补偿的外部事实，而不是依赖补偿事务。
|
||||
|
||||
## 决策
|
||||
|
||||
1. 已存在旧 active 的 `upgrade|reinstall|rollback` 在 `staged → activating` 之前必须依次通过所有前置条件。Secret binding/transition
|
||||
receipt 先完成；随后从 staged install、immutable lock 和 content-addressed bytes
|
||||
构建目标 resource generation，读取有硬上限的 Manifest/资源并执行完整语义物化。
|
||||
generation 1 没有可回退的旧指针，并且 Secret-aware 首次安装仍需 ADR-0395 的
|
||||
post-activation B1 binding ceremony，因此不进入本 ADR 的候选物化门。
|
||||
2. 候选 materialized revision 以既有 `generationDigest` repository key 在激活前发布。
|
||||
相同 revision exact replay 返回 existing；不同事实冲突。该 revision 尚不构成 active，
|
||||
Task reconciliation、Automation publication 与 Tool snapshot 仍只消费 active generation。
|
||||
3. 确定性的候选语义错误或 durable revision 冲突把当前安装从 `staged` 原子推进为
|
||||
`failed(reason=activation_fact_conflict)`。状态机必须保留
|
||||
`activeLockDigest=previousActiveLockDigest`，并且 activation publisher 调用次数为零。
|
||||
4. OCI、文件、SQLite/PostgreSQL 或 reader close 的瞬时不可用不写失败事实，安装保持
|
||||
`staged` 并由既有有界 recovery 重试。不得在不可区分时把可用性故障伪装成坏包。
|
||||
5. active pointer 发布成功后，既有 Task publication recovery 复用预先持久化的 revision，
|
||||
只执行 generation-fenced reconciliation；它继续承担响应丢失与并发 superseded 检查。
|
||||
6. Local 与 Cluster 必须使用同一个 runtime-core prerequisite sequence 和候选物化实现。
|
||||
Local 复用单 SQLite authority 与本地 staging reader；Cluster 复用 caller-driven recovery
|
||||
Job、单 PostgreSQL Pool、OCI reader 与 Kubernetes CAS publisher。
|
||||
7. 本决策不增加 workspace package、migration、表、第三方依赖、daemon、timer、watcher、
|
||||
listener、连接池或常驻 cache。Edge/Standalone 只在已有启动恢复遇到 staged install 时
|
||||
按需读取候选字节；没有待恢复安装时只创建少量短生命周期对象，不增加后台 cadence。
|
||||
|
||||
## 接受条件
|
||||
|
||||
- 共享测试证明有效候选在激活前发布且 exact replay 不重复写；语义无效候选不发布 revision。
|
||||
- 升级恢复测试证明 rejected 候选进入 failed、旧 active lock 保留且 publisher 未调用。
|
||||
- Local 与 Cluster 组合测试证明恢复顺序一致，既有 active publication/reconciliation 不回归。
|
||||
- 完整 18-package、backend、package/dependency/deployment/edge/import 审计通过。
|
||||
- 真实 PostgreSQL/Kubernetes 门证明失败升级没有移动 active ConfigMap/head；physical HA 门通过。
|
||||
- 固定物理低配设备证据仍由 ADR-0396 单独阻断，不能用开发机观测替代。
|
||||
|
||||
## 影响与替代方案
|
||||
|
||||
- 失败候选可能留下一个不可达、不可变的 materialized revision。它按 generation 有界，保留
|
||||
失败取证事实；物理清理由独立 retention/GC receipt 决定，不在失败路径同步删除。
|
||||
- 不把 materialization 塞入 Kubernetes publisher。Publisher 只拥有 pointer CAS 与投影
|
||||
evidence；让它读取 OCI/PostgreSQL 会聚合执行和发布 authority。
|
||||
- 不新增 `rolling_back` 状态。指针从未移动时，健康旧版本本来就仍是 active；新增补偿状态
|
||||
只会扩大恢复矩阵并让低配设备承担无收益的持久化协议。
|
||||
|
||||
## 当前验证
|
||||
|
||||
- Runtime Core 定向 21/21 通过，覆盖前置条件顺序、候选预物化、exact replay、无效语义拒绝、generation 1 B1 兼容和升级失败保留
|
||||
旧 `activeLockDigest`；拒绝路径的 activation publisher 调用次数为零。
|
||||
- Local Application 47 pass/4 条件 skip；Cluster Admin 347 pass/3 条件 skip。Cluster 首次在
|
||||
沙箱内运行的 32 个失败均为回环监听 `EPERM`，在允许本机监听的环境重跑后全部通过。
|
||||
- 18-package clean build/test 退出 0；Runtime Core 548/548；backend 1196 项为
|
||||
1194 pass/2 条件 skip/0 fail。package boundary 保持 18 个 package 且
|
||||
`singleSourcePackages=[]`、`shallowSourcePackages=[]`；cluster dependency、cluster deployment
|
||||
与 edge import 审计均无 finding。
|
||||
- PostgreSQL `18.4` arm64 physical HA 通过 125 项门，timeline `1→2`，报告 SHA-256
|
||||
`75d7a52be75c22b2aacf32f2d7e2c432a467ebaab4d639668ff3a4b98767a17e`，临时 Docker
|
||||
资源已清理。真实 Kubernetes 失败升级未移动 active pointer/head 的现场门与固定物理低配设备
|
||||
证据仍待完成，因此本 ADR 保持 Proposed。
|
||||
@@ -401,6 +401,7 @@
|
||||
| [ADR-0395](./ADR-0395-owner-confirmed-plugin-package-secret-binding.md) | Owner 确认的 Plugin Package Secret 首次绑定 | Proposed |
|
||||
| [ADR-0396](./ADR-0396-generation-transition-plugin-package-secret-binding.md) | 按 Package Generation 切换 Plugin Package Secret Binding | Proposed |
|
||||
| [ADR-0397](./ADR-0397-explicit-cluster-secret-action-manual-recovery.md) | Cluster Secret Action 显式人工恢复 | Accepted（实现、单节点 PostgreSQL、完整 workspace/后端/边界与 physical HA 门完成） |
|
||||
| [ADR-0398](./ADR-0398-pre-activation-plugin-package-candidate-qualification.md) | Plugin Package 激活前候选资格校验与自动保留旧版本 | Proposed（实现、全量/HA 门完成，Kubernetes 失败升级与物理低配门待闭合） |
|
||||
|
||||
## 规则
|
||||
|
||||
|
||||
Reference in New Issue
Block a user