qinglong/docs/adr/ADR-0295-shallow-profile-package-dependency-firewall-proof.md

ADR-0295：浅层 Profile Package 的依赖防火墙证明

• 状态：Accepted
• 日期：2026-08-09
• 关联：D-05、D-06、D-17、D-85、D-87、D-213、D-257、ADR-0063、ADR-0106、ADR-0267、ADR-0276、ADR-0294

上下文

QL3 当前 19 个 workspace package 中没有单 source package，但 @qinglong/local-profile 与 @qinglong/local-adopted-profile 都只有三个 src/ 根文件、没有嵌套实现。仅凭“这些文件是公开入口”的文字解释还不够： 如果任何 artifact label 加几个 wrapper 都能取得浅层例外，package hard cap 只能限制总数，不能阻止边界逐步碎片化。

另一方面，这两个 package 不能按文件数机械合并。基础 local-profile 的 production closure 只允许 SQLite storage； local-adopted-profile 才安装 local-admin、Local Secret 与 legacy source 写栅栏。继续向上合入 local-application 又会带入 local-execution、local-process 和 Croner。Edge/Standalone 的固定入口已经由 ADR-0106 从四个独立 wrapper package 收敛为 subpath，当前三个根文件分别对应 root、Edge 和 Standalone 公开入口，并非平铺 实现。

当前强制 GitNexus 中，package boundary audit 和 shallow-layout parser 均为 LOW，分别只有 1 个直接调用、0 条产品执行流； 两个 Profile 运行时 symbol 不需要修改。

决策

1. 保留 @qinglong/local-profile 与 @qinglong/local-adopted-profile 两个 package。它们隔离的是 production dependency、 authority 和制品闭包，不是按文件数量划分的代码职责。
2. docs/ql3-package-boundaries.json 升级为 schema v3。所有无嵌套 source、无独立 binary、仅靠 artifact 证明 deployable 的 package，必须在 shallowSourceLayout 中同时声明：
   • artifact 名到 package export specifier 的精确映射；
   • 一个真实直接 consumer 作为相邻更大闭包；
   • 至少一个存在于 consumer closure、但不存在于自身 closure 的 production dependency。
3. 审计必须从实际 package manifests 递归计算 production dependency closure，不接受账本自报；比较对象必须是该 package 的真实直接 consumer，delta dependency 必须在 workspace 或外部 production closure 中可证明。
4. 对 shallow artifact package，manifest 的全部 export specifier、runtime .js target、根 source output 和 artifact entrypoint 必须形成一一对应；隐藏 export、孤立根文件、重复 target、虚构 artifact 或未证明 dependency delta 均失败。
5. 有真实 bin 的 shallow deployable 继续以 executable manifest 作为独立部署证明，不强制使用 artifact dependency delta； one-source、consumer、authority、adapter 和 package hard-cap 的既有规则继续生效。
6. local-profile 必须证明相对直接 consumer local-adopted-profile 排除 local-admin 与 local-secret； local-adopted-profile 必须证明相对直接 consumer local-application 排除 local-execution、local-process 与 croner。
7. 不改两个 package 的 public API、运行实现、依赖树、artifact 集合或 Profile 行为；本批只加强结构准入，不以门禁改造伪装 运行重构。

被拒绝的方案

• 合并两个 Profile package：基础路由器闭包会取得 adoption 管理 authority，违反低配与最小权限边界。
• 把 adopted 组合并入 local-application：storage-only adopted artifact 会被执行器、进程适配器和 Croner 污染。
• 只按 LOC/source 数设置自动合并阈值：无法表达依赖、authority、部署和消费者责任，会误删安全边界并鼓励拆空 wrapper。
• 维持 schema v2 的文字 rationale：能解释当前状态，但不能阻止下一批浅层微包复制相同说法。
• 为 Edge/Standalone 恢复独立 package：ADR-0106 已证明固定配置值只需要 subpath，不构成依赖边界。

接受条件

1. 当前两个 shallow package 的入口、artifact 和 dependency firewall 由实际 manifest/closure 计算证明，审计 compatible:true。
2. fixture 必须拒绝缺少 closure delta、比较非 consumer、依赖在两边都不存在、export/artifact 漂移和隐藏根入口。
3. 两个 Profile package 定向测试、完整 19-package 与 backend package-boundary 回归通过。
4. cluster dependency、package boundary、Edge import、local image 与十档 artifact/RSS 门通过；基础 Edge/Standalone 仍不安装 local-admin/adoption authority。
5. 强制 GitNexus 和 detect_changes 证明没有产品执行流、运行 symbol 或 production dependency 变化。

接受证据

2026-08-09 已完成：

1. package boundary ledger 已升为 schema v3，审计从实际 manifest 递归计算 production dependency closure；当前 workspacePackageCount=19、singleSourcePackages=[]，只有 local-profile 与 local-adopted-profile 被识别为 shallow， 且 compatible:true。
2. 六项 package-boundary fixture 全部通过，明确拒绝缺少 artifact/delta 证据、虚构 delta dependency、以非 consumer 比较、export/artifact 漂移和隐藏根入口；完整 backend 为 1,111（1,109 pass/2 skip）。
3. local-profile 5/5、local-adopted-profile 8/8，完整 19-package clean build/test 全绿。cluster dependency、package boundary、Edge import 与 local image 四项相关审计均 compatible。
4. 十档实际 pack/offline-install/import/RSS 门全部通过，字节/文件/module closure 与改造前完全相同：
   • Edge 3,635,004 bytes/332 files/48 modules；Standalone 3,635,052/332/48；
   • Edge Adopted 4,246,392/372/49；Standalone Adopted 4,246,476/372/49；
   • Edge Application 4,735,631/427/105；Standalone Application 4,735,775/427/105；
   • Edge AI 5,021,770/396/49；Standalone AI 5,021,830/396/49；
   • Edge Application AI 6,122,469/491/104；Standalone Application AI 6,122,625/491/104。
5. 基础 Edge/Standalone 的生产集合仍只有 local-profile、local-sqlite、runtime-core、semver；Adopted 才安装 local-admin/local-secret，Application 才安装 local-execution/local-process/croner。强制 GitNexus 为 43,278 nodes/98,485 edges/1,699 clusters/269 flows；shallowSourceLayout 与 auditPackageBoundaries 均为 LOW、0 affected process，detect_changes all/compare develop 仍为 12 files/31 symbols 与 14/34，均 low/0 process。本批没有 修改运行 symbol、public API、production dependency、migration 或部署单元，因此不重复制造 PostgreSQL HA 物理晋升证据。