feat(ql3): establish 3.0 incubation baseline

docs/adr/ADR-0139-kubernetes-plugin-package-active-pointer-cas.md

@@ -0,0 +1,157 @@
+# ADR-0139：Kubernetes Plugin Package Active Pointer CAS
+
+- 状态：Accepted（ConfigMap exact pointer、stage evidence verifier、
+  resourceVersion CAS、并发/读取窗口/响应丢失恢复与 subpath 门禁已实现；ADR-0140
+  已补 durable startup recovery、标准 OCI verifier、一次性 admin process、独立
+  image 与最小权限 Job/RBAC；真实集群专项门仍待完成）
+- 日期：2026-07-24
+- 关联 RFC：QL-RFC-0001 D-08、D-09、D-132、D-135 至 D-137
+- 关联 ADR：ADR-0087、ADR-0129、ADR-0134、ADR-0138
+
+## 背景
+
+ADR-0138 已冻结完整 activation intent、fresh publish 与 recovery inspect 的区别，并
+实现本地 POSIX pointer。PostgreSQL Repository 也已能耐久保存 Cluster installation
+和 PackageLock，但没有跨 admin 副本可见的 active pointer publisher。
+
+Cluster 不能复用本机文件锁；也不能把 active generation 只写数据库后假定 Kubernetes
+资源已发布。另一方面，为一个 ConfigMap adapter 新增 workspace package会继续加剧
+packages 过细，而 `@qinglong/cluster-admin` 已拥有受审 Kubernetes client 依赖和
+短生命周期 mutation authority。
+
+## 决策
+
+### 1. Publisher 留在既有 cluster-admin
+
+新增显式
+`@qinglong/cluster-admin/plugin-package-kubernetes-activation` subpath，不从 root、
+administration 或 cluster-control production 入口导出。不新增 workspace package、
+第三方依赖、timer、watcher、cache、sidecar 或数据库 connection。
+
+runtime-core 新增共享 `normalizePluginPackageActivationIntent`，所有 Cluster pointer
+在读写前都使用 exact schema、identifier、digest 和 generation 上限；publisher 不复制
+第二套 activation intent 语义。
+
+### 2. 一个目标对应一个有界 ConfigMap
+
+目标 identity 固定绑定 cluster identity、namespace、Project 和 Package。资源名为
+`ql3p-` 加 domain-separated SHA-256 的前 208 bit；完整 256-bit target digest仍写入
+label 并在读取 canonical intent 后重算复验，因此名称截断不缩窄内容校验。
+
+ConfigMap：
+
+- `apiVersion=v1`、`kind=ConfigMap`、mutable；
+- data 只有 `active.json`，上限 32 KiB；
+- pointer exact 保存 schema、cluster identity digest、activation intent 和 receipt；
+- labels exact 保存 managed-by、active schema 和完整 target digest；
+- annotation exact 保存 intent digest；
+- 禁止 binaryData、deletion timestamp、finalizer 和 owner reference。
+
+资源名冲突或 metadata/data/pointer 漂移统一失败关闭。208-bit 名称只用于 Kubernetes
+寻址，完整 identity、lock、stage 双证据和 intent digest 才是 authority。
+
+### 3. stage evidence 由注入端口复验
+
+`ClusterPluginPackageStageEvidenceVerifier.verify(intent)` 必须返回并精确匹配：
+
+- lock digest；
+- stage reference；
+-领域 stage receipt digest；
+- adapter 外部 evidence digest；
+- content digest。
+
+publisher 在每次 inspect 以及 publication 最终复核时调用 verifier。具体实现可以是
+exact OCI digest、对象存储 receipt 或后续受审 Kubernetes 资源，但本 ADR 不允许
+publisher 自行下载、缓存或猜测来源。verifier 不可用返回 unavailable，事实漂移返回
+conflict。
+
+### 4. create/replace 使用 resourceVersion CAS
+
+首装只在 ConfigMap 不存在且 previous lock 为 null 时 create。升级先读取 current
+pointer，必须 exact 等于 previous active lock，再用该对象的 resourceVersion replace。
+
+第一次 observe 与取得写入 resourceVersion 之间存在第二次 GET；第二次返回的实际
+pointer必须再次复验 previous lock。否则另一个副本在窗口中发布新 generation 后，
+stale writer 会拿赢家的新 resourceVersion 将其覆盖。
+
+Kubernetes 409 只在重新 inspect 得到完全相同 intent 时作为 exact replay；其他 winner
+均为 conflict。两个并发候选最多一个成功。
+
+### 5. 响应丢失只由恢复 inspect 裁决
+
+create/replace 返回非 409 错误时，publisher 不在 fresh 路径猜测是否已经提交，而是
+返回 unavailable，让数据库 record 保持 `activating`。ADR-0138 coordinator 在恢复时
+只调用 inspect：
+
+- exact ConfigMap pointer → 提交 durable active receipt；
+- pointer absent → durable activation failure；
+- pointer 为其他 generation 或 tamper → durable fact conflict。
+
+成功 API 响应后仍要重新 GET pointer 并再次复验 stage evidence；不能只信 response
+body 或本地 request。
+
+### 6. 产品入口继续分阶段开放
+
+ADR-0140 已提供：
+
+- 标准 OCI Distribution stage evidence verifier；OCI manifest digest 与 bundle
+  layer digest 分离，签名通过 lock-annotated OCI referrer取得；
+- `ql3-plugin-package-recover` production admin binary；
+- 独立 cluster-admin image；
+- 仅有 ConfigMap `get/create/update` 的 ServiceAccount、Role/RoleBinding 和
+  600 秒一次性 Job manifest。
+
+仍不提供：
+
+- object-store stage；
+- Approved Action durable consumer、Policy/Audit route；
+- operator repair；
+- ADR-0149 active generation source 之上的 Task/Workflow/Prompt/Tool/Trigger
+  语义 materializer；
+- ConfigMap GC、Package byte distribution、Runtime/UI Extension。
+
+因此 adapter 可执行不等于 Cluster 已开放插件安装。
+
+## 拒绝的方案
+
+- 新增 `plugin-package-kubernetes` workspace package：拒绝；一个 adapter 文件没有
+  独立发布或运行生命周期，显式 subpath 足以隔离。
+- 只在 PostgreSQL 切 active generation：拒绝；无法证明 Kubernetes 可见事实已发布。
+- 使用普通 replace 或 merge patch：拒绝；缺少 exact previous resourceVersion fence。
+- 只校验第一次 GET：拒绝；第二次 GET 后可覆盖窗口中的新赢家。
+- 在 publisher 内实现 OCI client：拒绝；会合并来源、缓存、stage 与 pointer authority。
+- 将 ConfigMap 设为 immutable 并每 generation 新建：拒绝；会把唯一当前 authority
+  退化为目录/label 扫描和 GC 问题。
+
+## 影响
+
+- Cluster 多副本获得单一、可 inspect、resourceVersion-fenced active pointer。
+- edge/standalone 不依赖 cluster-admin；共享 intent normalizer 使六种本机制品各增加
+  2,532 bytes，但 files 与 loaded modules 不变，最大值仍低于硬门禁。
+- packages importer 保持 21；cluster-admin 继续复用现有
+  `@kubernetes/client-node`，dependency audit 无新增 dependency。
+- Kubernetes client 只进入独立短生命周期 admin image；常驻 cluster-control
+  production closure 不变。
+- ConfigMap 只保存低敏摘要和 identity，不保存 bundle、Secret 或可执行内容。
+
+## 验证
+
+当前门禁覆盖：
+
+1. canonical ConfigMap create、inspect 和 exact replay；
+2. exact previous lock replacement 与 stale writer conflict；
+3. create response loss 后 inspect 收敛且不 republish；
+4. 同一 resourceVersion 的两个候选 single winner；
+5. 两次 GET 之间插入新 winner 时 stale writer 不覆盖；
+6. stage evidence drift 在任何 API mutation 前失败；
+7. ConfigMap pointer canonical/tamper fail-closed；
+8. root 不导出、显式 subpath 可达；
+9. runtime-core intent normalizer 与 generation 边界；
+10. cluster-admin 全量 55 pass/1 条件 skip，ConfigMap response loss 已通过 durable
+    startup recovery 在下一轮 inspect 收敛且不再次 create；
+11. 标准 OCI allowlist、manifest/layer/referrer/signature 与重启重新取证；
+12. 独立 admin image 的真实非 root、只读 rootfs CLI smoke；
+13. dependency/source 与 Kustomize/RBAC audit 仍为 21 importer、`findings=[]`。
+
+真实 Kubernetes API 的 ConfigMap 专项 CAS、RBAC 正负向和多 Pod response-loss fault
+仍是产品开放前的独立 Gate。