qinglong/docs/adr/ADR-0357-thin-package-root-and-stable-export-map.md

ADR-0357：薄 Package 根目录与稳定 Export Map

• 状态：Accepted
• 日期：2026-08-10
• 关联：QL-RFC-0001 D-269、ADR-0296、ADR-0304

上下文

QingLong 3.0 的 17 个 workspace package 已按部署边界与 authority 拆分，但物理目录仍可能退化为另一种“平铺”：多个角色化公开门面堆在 src/ 根目录。@qinglong/cluster-postgres 曾有 10 个根文件，其中 9 个只是为 /runtime、/admin、/package-manager 等公开 subpath 聚合既有领域实现。它们不是新的领域或 authority，却让根目录看起来像实现目录，也提高了继续堆放横切逻辑的概率。

目录整洁不能以破坏调用方契约为代价。外部消费者依赖的是 package export specifier，而不是仓库内的 TypeScript 物理路径；测试和运维脚本若直接引用 dist 物理文件，则属于仓库内部耦合，必须随实现布局迁移。

决策

1. 有嵌套领域实现的 package，src/ 根目录只允许受审的主导出入口或二进制入口；普通实现不得回到根目录。
2. @qinglong/cluster-postgres 的 9 个角色化门面迁入 src/entrypoints/，src/ 根目录只保留 index.ts。
3. 对外的 @qinglong/cluster-postgres/runtime、/admin、/package-manager 等公开 specifier 保持不变；package.json#exports 映射到新的 dist/entrypoints/* 物理目标。
4. 不保留旧 dist/runtime.js 等物理兼容壳。仓库内测试和脚本改用新物理目标或公开 specifier，防止双入口长期漂移。
5. docs/ql3-package-boundaries.json 将该 package 的根文件硬上限从 10 收紧为 1、根行数上限收紧为 125；CI 必须验证精确根文件角色、导出目标存在、旧根门面不存在。
6. 本次调整不创建新 workspace package、不改变 authority、不增加运行依赖，也不扩大 Edge/Standalone 闭包。

放弃的方案

• 保持 10 个根门面：公开 API 可用，但根目录继续成为无领域归属代码的默认落点。
• 为每个门面创建 package：把目录问题放大成部署与依赖问题，尤其伤害低配设备闭包。
• 保留旧 dist 兼容壳：形成两套可加载物理入口，测试可能绕过 export map，长期更难收敛。
• 直接修改公开 subpath：没有产品收益，却给 Cluster Control、Cluster Admin 和外部扩展制造迁移成本。

影响

• package 根目录更接近“接口面”，领域目录继续承载实现。
• 公开 import specifier 和类型契约不变；只依赖未承诺物理 dist 路径的仓库内部代码需要同步更新。
• package 数仍为 17；994 个源码文件中根文件由 26 降为 17，嵌套文件由 968 增为 977（98.3%）。
• 后续若确需增加根入口，必须先修改边界账本并给出角色与行数证据，不能静默增长。

验证

• 17 个 QL3 package 干净顺序构建通过。
• Package boundary audit compatible，8/8 边界回归通过。
• Cluster dependency audit compatible。
• PostgreSQL package：292 pass、1 条件 skip、0 fail。
• Cluster Control：186 pass、2 条件 skip、0 fail。
• Cluster Admin：269 pass、2 条件 skip、0 fail。
• 9 个既有 PostgreSQL 公开 subpath 均通过 Node 加载验证。