qinglong/docs/adr/ADR-0040-profile-activation-and-edge-import-isolation.md

ADR-0040：Profile 激活顺序与 Edge 导入隔离

• 状态：Proposed
• 日期：2026-07-19
• 关联：QL-RFC-0001、ADR-0036、ADR-0038、ADR-0039

上下文

独立 migration stream、schema readiness 和独立 cluster package 仍不能单独证明部署安全。两个装配错误会直接破坏 Profile 边界：

1. cluster-control 在 readiness 前创建 Repository、启动恢复 timer 或注册 admission；
2. edge 虽然不执行 cluster 路径，但根 importer 或启动导入闭包仍安装、解析或加载 PostgreSQL/Drizzle bundle。

前者会让不兼容 schema 或过度授权 role 在 fail-closed 之前产生业务副作用；后者会让低性能路由设备承担无用的安装体积、native/供应链风险和启动内存。仅使用动态 import() 只能推迟模块求值，不能从 edge lockfile、镜像或安装树中移除依赖。

决策

1. Cluster-control 只有一个有序激活门

cluster-control 的启动顺序固定为：

1. 明确启用且 Profile 精确为 cluster-control；
2. 执行 ADR-0039 的只读 readiness；
3. readiness 成功后才创建业务 Repository 和 runtime stack；
4. 先执行有界 startup recovery，并证明 safe=true、remaining=0、failed=0；
5. 再启动 claim、recovery 等 lifecycle；
6. 最后安装 admission，使 API、scheduler 或其他 producer 可以提交新工作。

禁用时不得查询数据库、创建 stack、启动 timer 或安装 admission。错误 Profile 必须在数据库探测前拒绝。readiness 成功不是自动接管信号，只有完整顺序全部完成后状态才是 active。

2. 失败与停止采用反向撤销

stack 创建后的任一步失败都必须：

1. 撤销已安装 admission；
2. 有界停止已创建的 lifecycle/stack；
3. 写低敏失败审计；
4. 保留原始激活错误，不用 cleanup 或 audit 错误覆盖根因。

正常停止同样先关闭 admission，再停止 stack。停止必须幂等；重复调用共享同一个停止结果。installAdmission() 必须自身具备原子安装或失败回滚语义，不能抛错后留下不可撤销的半注册入口。

数据库资源由外层 lazy bootstrap 管理：只有已启用且 Profile 为 cluster-control 时才调用 openDatabase()。readiness、assembly 或 activation 任一步失败，都在保留原错误后关闭数据库；active shutdown 必须先完成 admission/stack stop，再关闭 Pool。Pool close 失败不得跳过 stack stop，重复 stop/close 共享同一 Promise。

3. Readiness evidence 只授权本次装配

Repository factory 接收本次 readiness evidence，用于绑定 contract name/version、PostgreSQL major 和 migration IDs。evidence 不是永久缓存，也不能跨数据库、凭据或进程复用。连接重建、role 变化或数据库 failover 后，实际 production adapter 必须按运维策略重新证明 readiness；不得用旧 evidence 绕过检查。

4. Edge 根 importer 不得声明 cluster 依赖

edge/standalone 共用的根 package.json 在以下区段都不得声明 pg、pg-native、drizzle-orm、drizzle-kit、@types/pg 或 cluster package：

• dependencies
• devDependencies
• optionalDependencies
• peerDependencies

PostgreSQL driver、Drizzle schema/tooling 和 cluster-control assembly 只属于 ADR-0038 定义的独立 workspace/package 与 profile-specific 产物。根包的 dynamic import、optional dependency 或 install-time feature detection 均不能替代该边界。

5. Edge CI 同时审计 manifest 与代表性导入闭包

CI 必须在 edge Profile 下导入代表性的：

• Profile/resource policy；
• standalone/manual Primary 的轻量 bootstrap；
• headless Worker application runtime。

新增模块闭包不得包含 PostgreSQL migration 实现、pg、pg-native、Drizzle 或 cluster package。该门禁用于尽早发现静态 value import、barrel re-export 和 bootstrap 回归；它不等同于最终产物证明。独立 importer 落地后，还必须对 edge package tarball/镜像的 lockfile、安装树、SBOM、压缩体积与冷启动 RSS 做闭环审计。

当前孵化状态

next 已实现默认不可达的 activateClusterControlRuntime()：

• 错误 Profile 在 readiness 前拒绝；
• readiness 失败前不会调用业务 factory；
• 成功路径固定 readiness → assembly → recovery → lifecycle → admission；
• unsafe/incomplete recovery 会停止 stack，且不会开放 admission；
• admission-first shutdown 和重复 stop 已有契约测试。

独立 @qinglong/cluster-control 的 bootstrapClusterControlRuntime() 已把 lazy database、ADR-0039 readiness、ADR-0041 Run Repository 与激活门串联：disabled/错误 Profile 零打开，readiness 通过后才创建真实 PostgresRunRepository 和业务 stack，失败自动关闭，正常关闭顺序固定为 admission → stack → Pool。真实 openDatabase() 由 @qinglong/cluster-postgres 提供，组合根不读取 legacy back/**。

同时已加入 audit:edge-imports:ql3：

• 检查根 manifest 的四类依赖区段；
• 导入三个代表性 edge/standalone/worker 入口；
• 检查新增 require.cache 闭包是否触达 cluster bundle；
• 纳入 Node 20/24、x64/arm64 的 QL3 CI 矩阵。

ADR-0045 已在独立 package 增加有界 HTTP application host、/livez、activation-backed /readyz 和 fail-closed /api/v3 admission，并把 disposer 升级为可异步 drain：停止先拒绝新请求、向在途 handler 传播 Abort，真实 handler 未结束时不能继续宣称排空。公开 config 入口先解析 Profile/enable，禁用时不读取 PostgreSQL Secret；application/config 导入闭包不含 migration DDL 或 legacy 根。

当前仍没有认证/Policy-fenced 业务 router、完整 production recovery/lifecycle stack、独立 cluster 镜像/SBOM 或 failover 演练。现有 host 是 executable application boundary，但尚不是完整可部署控制面，不能据此开启匿名或生产 cluster-control API。

影响

正面影响：

• schema/role 不兼容时不会提前构造可产生业务副作用的对象；
• startup recovery 与新流量之间存在可测试的硬顺序；
• edge 对 cluster 依赖的隔离从文档约束变为 CI 约束；
• 正常停止、部分启动失败和重复停止具有同一 ownership 语义。

代价与风险：

• 新 lifecycle 必须接入统一 stack，不能自行在模块加载时启动；
• readiness catalog 扫描会增加一次启动成本，需要 timeout、节流与重新证明策略；
• 代表性 CommonJS 导入审计无法发现所有 bundler、ESM tree 或容器打包错误；
• 独立 workspace 落地后，CI 还需同时证明 cluster 产物包含依赖、edge 产物排除依赖。

未选择的方案

1. Repository 创建后再做 readiness：constructor、pool hook 或 timer 已可能产生副作用，拒绝。
2. recovery 与 admission 并行启动：新工作会扩大未收敛状态，拒绝。
3. readiness 失败后回退 SQLite：形成双事实源并违反 Profile 边界，拒绝。
4. 只依靠 dynamic import：不能降低安装体积或供应链暴露，拒绝。
5. 只检查根 package.json：无法发现 barrel/value import 回归，拒绝。
6. 只检查运行时 require cache：无法证明未加载包不存在于 edge 产物，拒绝。

验证要求

• disabled 路径无数据库、factory、timer 和 admission 行为；
• disabled/错误 Profile 不调用 openDatabase()，也不触发 driver dynamic import；
• 非 cluster-control Profile 在数据库探测前失败；
• readiness 失败保持原错误，且业务 factory 调用次数为零；
• recovery unsafe、remaining 或 failed 非零时不得启动 lifecycle/admission；
• lifecycle 启动失败或 admission 安装失败会反向清理；
• active stop 先同步切换 not-ready/拒绝新 admission，再异步等待在途 handler 结束，之后才停止 stack；drain timeout 显式失败且重复 stop 幂等；
• readiness/assembly/activation 失败关闭数据库；active stop 在 stack 后关闭 Pool，close 失败不覆盖更早的激活/停止错误；
• edge 根 manifest 出现任一禁止依赖时 CI 失败；
• 代表性导入闭包触达 PostgreSQL/Drizzle/cluster 路径时 CI 失败；
• 独立 package 落地后，edge tarball/镜像的 lockfile、SBOM 和安装树不包含 cluster bundle；
• PostgreSQL 16/18 role integration 通过后，才允许真实 cluster factory 接入激活门。