feat(ql3): establish 3.0 incubation baseline

docs/adr/ADR-0237-capability-oriented-dependency-boundary-reconciliation.md

@@ -0,0 +1,136 @@
+# ADR-0237：面向能力的依赖边界对账
+
+- 状态：Accepted
+- 日期：2026-07-31
+- 关联 RFC：QL-RFC-0001 D-175、D-207、D-210、D-211、D-213、D-221
+- 关联 ADR：ADR-0217、ADR-0220—0222、ADR-0229、ADR-0230、ADR-0236
+
+## 背景
+
+QingLong 3.0 的 Package 生命周期、自动化发布和 Workflow Task 纵切面完成后，仓库级
+依赖审计报告 27 条 finding。它们混合了两类不同问题：
+
+1. `cluster-admin` 的安装清单查询直接实例化
+   `PostgresPluginPackageInstallRepository`。该 concrete adapter 同时实现 inventory、
+   admission 和 install mutation port；即使调用方只使用两个查询方法，composition 已经
+   取得 executor authority，违反 ADR-0220 的 package-manager 只读边界；
+2. 新增的 lifecycle/publication 文件与 Local Workflow 内部依赖已经由 ADR 定义，但
+   依赖审计的具体文件/subpath 清单仍停留在旧切片。
+
+如果把两类 finding 都简单加入白名单，会掩盖真实权限泄漏；如果按每个共享 port 再拆
+workspace package，则会重回“一文件一包”，增加路由设备的安装、构建、SBOM 和供应链
+成本。
+
+## 决策
+
+### 1. 先区分 capability 泄漏与审计规则滞后
+
+依赖审计 finding 不能直接以“代码已经存在”为理由放行。每条新边必须满足：
+
+- 对应已有 RFC/ADR 的部署和 authority 方向；
+- 只开放到具体 owner 文件和具体 package subpath；
+- 不让只读进程取得 mutation concrete adapter；
+- 不增加 Profile 无关的重依赖或常驻资源；
+- 仍有负向测试证明相邻的宽入口和反向依赖被拒绝。
+
+### 2. Package manager 使用独立只读 inventory reader
+
+`cluster-postgres` 增加
+`PostgresPluginPackageInstallInventoryReader`，只实现
+`PluginPackageInstallInventoryRepository` 的 `findCurrent` 和
+`listCurrentPage`。它只从 `@qinglong/cluster-postgres/package-manager` 导出；该入口
+不得导出 `PostgresPluginPackageInstallRepository`，reader prototype 也不得出现
+admit/create/commit/recovery 方法。
+
+`cluster-admin/pluginPackageManagement` 改为只装配该 reader。原 mutation repository
+继续留在显式 `plugin-package-install`/package-executor 权限边界，既有安装与恢复语义不
+修改。
+
+### 3. Workflow Task repository port 上提为 package 内共享契约
+
+`LocalWorkflowTaskExecutionRepository` 同时被 execution、control 和 recovery 使用，
+因此不属于 `execution/` 实现区。它上提到 `local-execution/src` 的共享契约文件；
+`./execution` 继续 re-export，保持公开 subpath 兼容。
+
+审计只允许各区域导入这一条精确共享 port，不开放任意 root 文件。Scheduler 依赖
+dispatch 是 ADR-0229 单 cadence 的最后一步，明确登记为
+`scheduler → dispatch → execution` 的单向 DAG；反向 `execution → dispatch`、
+`control → recovery` 等继续拒绝。
+
+### 4. 新纵切面使用具体文件 + 具体 subpath 清单
+
+以下边只对对应 owner 文件开放：
+
+- Owner CLI lifecycle command → local-admin lifecycle、SQLite install inventory 与
+  runtime lifecycle contract；
+- local-admin lifecycle service → SQLite approval/operation/lifecycle/policy authority 与
+  runtime approval/lifecycle/policy/security/audit contract；
+- local-application activation/contract → runtime automation publication contract；
+- Cluster lifecycle management → manager/approval/policy，lifecycle executor →
+  executor/approval/policy；
+- management transport → capability-free lifecycle plan DTO；
+- Cluster installation management → package-manager 只读入口。
+
+未知文件、根入口、driver、executor repository 或相邻 authority 不因这些决策获得通配
+权限。
+
+### 5. 不新增 workspace package
+
+workspace 保持 20 个 package。共享 port、只读 adapter 和审计契约都进入已有职责
+owner；它们没有独立部署、发布、重依赖、凭据、故障域或 Profile 替换价值。文件数量
+继续不作为拆包理由。
+
+## 不采用方案
+
+### 把 27 条 finding 全部加入宽白名单
+
+拒绝。会把 manager→executor concrete adapter 泄漏永久合法化，并让后续同 package
+文件获得未审 authority。
+
+### 让只读 reader 包装或继承 mutation repository
+
+拒绝。包装仍在 composition 内构造 mutation authority，继承则直接把 mutation 方法
+暴露在 reader 对象上，都不满足 capability 最小化。
+
+### 新建 inventory、workflow-contract 或 lifecycle workspace package
+
+拒绝。这些能力都由既有 package/进程 owner 使用，没有独立交付价值；拆包只会增加
+低配设备闭包和维护成本。
+
+### 直接允许 control/recovery 依赖 execution 实现区
+
+拒绝。共享 port 应属于中性契约层；允许反向实现依赖会使内部 DAG 失去约束。
+
+## 影响
+
+- workspace、生产依赖、migration、表、角色、进程、端口、Pool、timer、watcher、
+  listener 和常驻内存均不增加；
+- `@qinglong/local-execution/execution` 公共导出保持兼容；
+- PostgreSQL mutation repository 的已有方法和三个生产调用者不修改；
+- package-manager 只增加可审计的只读 capability，不获得 install mutation authority；
+- 依赖审计从 27 条 finding 收敛为 0。
+
+## 验证
+
+1. GitNexus impact：`PostgresPluginPackageInstallRepository` 为 CRITICAL（3 direct、
+   7 upstream），因此不修改其既有方法；
+   `createClusterPluginPackageManagementService` 为 LOW（1 direct、3 upstream）；
+   `LocalWorkflowTaskExecutionRepository` 为 MEDIUM（5 direct、20 upstream）；
+   `auditSourceImports` 为 LOW（1 direct）；
+2. cluster-postgres、cluster-admin 与 local-execution strict TypeScript closure check
+   通过；
+3. 依赖审计报告 `findings=[]`、`compatible=true`，20 个 importer 不变；
+4. 依赖边界 38/38，通过精确 lifecycle/publication 正向边、共享 port、scheduler DAG，
+   并继续拒绝 manager→executor concrete adapter 和内部反向依赖；
+5. package-manager entrypoint 证明只读 reader 可达、mutation repository 不可达，
+   reader prototype 仅有 constructor/findCurrent/listCurrentPage；另以无 connect、无
+   mutation 的 query-only pool 实际验证 exact/list 和 `limit + 1` 参数；
+6. 受影响包全量测试：cluster-postgres 249 pass/1 条真库条件 skip、cluster-admin
+   133 pass/1 条真实 Kubernetes 条件 skip、local-execution 30/30；Cluster Admin 两个
+   过期 role fixture 同步拒绝三个 runtime-only function，生产 readiness 未放宽；
+7. PostgreSQL `18.4 (Debian 18.4-1.pgdg13+1)` arm64 physical HA 通过
+   `remote_apply`、timeline 1→2、旧主先 fencing、`pg_rewind` 只读同步重入和两个 fresh
+   control replicas；inventory 提升前为 quarantined、list 有结果、提升后存活，全部具体
+   gate 与 `gates.passed=true`；
+8. HA 临时容器、网络和卷已清理；已有且与本门无关的
+   `ql3-cnpg-evidence-control-plane` 未修改。