feat(ql3): establish 3.0 incubation baseline

docs/adr/ADR-0219-pinned-semver-runtime-adapter-boundary.md

@@ -0,0 +1,123 @@
+# ADR-0219：固定 SemVer 运行时适配器边界
+
+- 状态：Accepted
+- 日期：2026-07-29
+- 关联 RFC：QL-RFC-0001 D-05、D-14、D-35、D-89、D-175、D-209
+- 关联 ADR：ADR-0106、ADR-0126、ADR-0128、ADR-0217、ADR-0218
+
+## 背景
+
+`@qinglong/runtime-core` 的 Remote Worker placement、Tool registry、Trusted Tool
+invocation、Plugin Package manifest 与 Plugin Package install 五个领域文件分别维护了
+一份私有 `semver()` loader。前三份使用 `typeof import('semver')`，因此 TypeScript
+builder 还必须安装 `@types/semver`；后两份则各自手写了不完全相同的结构类型。
+
+真实生产行为始终来自 exact `semver@7.7.4`，但重复边界产生了三个问题：
+
+1. 同一第三方 provider 有五个加载与类型 authority，容易在升级时产生能力漂移；
+2. base/adopted、local application、Worker、cluster-control 与 cluster-admin builder
+   都被迫携带只服务于编译的 `@types/semver`；
+3. `runtime-core` 的第一方接口实际上只消费 `valid`、`validRange`、`compare` 与
+   `satisfies`，却把第三方完整声明面传播给了领域实现。
+
+这不是删除生产 SemVer，也不能用手写 parser 或字符串比较替代真实库。
+
+## 决策
+
+### 1. 单一 package-internal provider adapter
+
+`packages/ql3-runtime-core/src/pinnedSemver.ts` 是唯一允许直接
+`require('semver')` 的 QL3 源文件。它声明最小结构接口 `PinnedSemverApi`，只包含：
+
+- `valid`；
+- `validRange`；
+- `compare`；
+- `satisfies`，包括既有 `includePrerelease` 选项。
+
+adapter 保持惰性加载与单实例缓存。五个领域文件只通过相对 import 消费该 adapter；
+不为它增加 package export/subpath，也不新增 workspace package。
+
+依赖审计以 exact 文件白名单固定该 authority，任何其他 QL3 源文件直接导入 SemVer
+都失败。
+
+### 2. 保留真实生产依赖，删除冗余声明依赖
+
+`@qinglong/runtime-core` 继续直接声明 exact `semver@7.7.4`。本决策只删除
+`@types/semver@7.5.8`：
+
+- runtime-core workspace importer；
+- cluster-control builder；
+- cluster-admin builder；
+- local-application builder；
+- 对应 builder lock 与审计期望。
+
+production manifest、runtime lock、SBOM 和 OCI runtime closure 不改变。结构类型由
+第一方代码维护，真实 SemVer 算法仍由锁定生产包执行。
+
+### 3. 行为兼容约束
+
+五个调用面的参数、返回判定、异常传播与 prerelease 行为保持不变。尤其：
+
+- canonical version 仍要求 `valid(value) === value`；
+- version range 仍由真实 `validRange` 判定；
+- Plugin Package 与 Remote Worker prerelease 匹配仍显式使用
+  `includePrerelease: true`；
+- registry 排序仍使用真实 `compare`。
+
+本次 alpha 内部重构不增加兼容 facade。
+
+## 不采用方案
+
+### 保留五个 loader
+
+拒绝。它没有部署隔离价值，只复制第三方边界并扩大 builder dependency。
+
+### 把 `@types/semver` 移到 root 或共享 builder
+
+拒绝。会隐藏依赖 ownership，且继续让低配 Profile 的 builder 闭包承担无关声明包。
+
+### 手写 SemVer parser 或只比较字符串
+
+拒绝。range、prerelease 与 canonical version 语义复杂，重新实现会产生兼容和安全
+风险。本决策只收口真实库的调用边界。
+
+### 新建 `semver-provider` workspace package
+
+拒绝。单文件、单消费者 package 不满足 D-175/D-207 的独立部署、权限、重依赖隔离或
+跨闭包复用价值。
+
+## 影响
+
+- workspace 保持 20 个 package；
+- production 仍安装并审计 `semver@7.7.4`，运行时能力没有减少；
+- 四个 builder manifest 不再声明 `@types/semver`；
+- 领域文件不再依赖 DefinitelyTyped 的完整第三方类型面；
+- 本机 adopted 制品与 PostgreSQL HA 门可越过 runtime-core，暴露各自真实的下一层
+  storage dependency 阻塞。
+
+## 验证
+
+1. GitNexus 将五个旧 loader 判为 2 个 HIGH、3 个 CRITICAL；最大影响 47 个上游
+   符号，涉及 Trusted Tool、Plugin Package 与 Remote Worker。改动因此保持真实 provider
+   与调用语义不变，并对这些流程执行专项回归；
+2. runtime-core build 通过，全量 369/369；
+3. adapter、五个领域调用面与依赖 import boundary 定向 90/90；
+4. dependency/deployment/SBOM/OCI/local-image 契约 101/101，production
+   component/node 数不变；
+5. 三个容器 builder lock 已从本地缓存离线重生成，当前 build dependency 审计仅保留
+   Node、PostgreSQL 与 TypeScript 必需声明；
+6. 首次 PostgreSQL HA 门已成功越过 runtime-core，并准确暴露
+   `cluster-postgres` 未物化的 `pg`、`drizzle-orm`；随后从本机受审
+   control/admin image 临时提取 exact production closure，三个 Cluster package
+   均完成 TypeScript build；
+7. edge-adopted 制品门已成功越过 runtime-core，当前由 `local-sqlite` 未物化的
+   `drizzle-orm` 阻断；
+8. 临时物化后的完整 `cluster-admin check → cluster-control check → HA Docker`
+   总门通过 PostgreSQL 18.4 arm64 的 35 个具体 gate 与总 `passed`；过程中还发现并
+   修正 HA CJS caller 未传 Cron provider，以及 Node 24 对 Kubernetes Node-stream
+   pair 类型建模不足的问题，PortForward/TLS 定向测试 9/9；
+9. 所有临时 package-local link 和 HA Docker container/volume/network 已清理。
+
+因此本 ADR 已证明 SemVer 边界、builder closure 与本机 HA runtime 一致；但本机镜像
+临时物化不能替代常规 registry 安装、远端 CI、六 Profile 物理 bytes/files/RSS 或
+未物化 local-sqlite dependency 的完成证据。