ADR-0257：Profile 运行制品裁剪与分层 Import RSS 预算

状态：Accepted
日期：2026-08-01
关联 RFC：QL-RFC-0001 D-85、D-89、D-175、D-207、D-240
关联 ADR：ADR-0042、ADR-0185、ADR-0217、ADR-0256
Supersedes：ADR-0185 中“所有 Profile 共用 16 MiB import RSS delta”与未区分开发包/运行制品的部分；不改变其 package 边界和文件/字节预算

背景

D-239 完成后，按真实 pnpm pack -> offline install 重跑十种本机 Profile，暴露出三个不同问题：

storage-only 安装闭包超过 512 files；
adopted assembly 没有显式携带 local-admin 运行时需要的 local-secret；
application 为 741 files、约 6.40 MiB，入口 import RSS delta 约 20.2--20.35 MiB，超过原 640 files / 5 MiB / 16 MiB 门。

逐文件核算发现，内部 npm 包中的 .d.ts 和 .map 占用了大量部署 inode/bytes，但 Node 运行时不消费它们。另有两处不必要的 eager import：fresh/disabled adoption 在读取启用开关前加载 admin runtime；通用 TaskDefinition repository 为抛出管理域错误而静态加载 administration 模块。它们是制品装配和入口依赖问题，不是新增 workspace package 的理由。

决策

1. 开发包与最终运行制品分离

内部 npm package 继续发布 dist/**/*.js 与 dist/**/*.d.ts，供 workspace、SDK 和类型消费； source、test、声明 map 和 JS map 仍由 packlist 规则排除。Profile assembler 在完成 exact offline install、核对精确 package closure 后，只从 node_modules/@qinglong/** 删除：

*.d.ts；
*.map。

不得裁剪第三方包、JavaScript、package manifest、受审 assets、Drizzle migration 或 native 文件；不得通过 ignore、symlink、未声明依赖或 workspace source 直接运行来制造通过。Docker local application 镜像必须执行同一内部运行制品裁剪，静态镜像审计同时验证两类删除命令。

2. 精确装配 adopted 与 application 闭包

adopted Profile 的 production closure 显式包含 @qinglong/local-secret。fresh/disabled adoption 入口先读取 enable gate，仅在启用后动态加载 @qinglong/local-admin/runtime；因此 storage-only 和 fresh adopted 不为迁移 authority 支付模块加载成本。

通用 SQLite TaskDefinition repository 不再静态导入管理域错误模块。事务 hook 抛出的精确错误实例原样传播，其他 storage failure 仍由既有 mapStorageError 处理；没有改变 repository 对外语义或放宽错误分类。

3. Profile 预算表达实际能力层级

文件和字节预算保持 ADR-0185 的分层，不因本次失败放宽：

能力层	文件上限	字节上限	import RSS delta 上限
storage-only	512	4 MiB	16 MiB
adopted compatibility	576	5 MiB	16 MiB
AI-only	640	5 MiB	16 MiB
application	640	5 MiB	24 MiB
application + AI	768	6 MiB	24 MiB

24 MiB 只表示在独立 Node probe 中加载完整 application capability entrypoint 后的 RSS 增量，不是设备总内存预算。Edge production process 仍至少按 96 MiB 暂定总物理预算规划，最终支持声明仍要求 Linux cgroup 和固定物理设备证据；不能用本门替代 cold start、峰值 RSS、执行并发或闪存证据。

4. 不改变 package 拓扑

workspace 保持 19 个 package，不新建 artifact-pruner、task-admin 或 profile wrapper 包，不新增 production dependency、migration、daemon、timer、watcher、listener、Pool、连接或端口。源码文件数量继续只触发 package 复审；合并仍必须证明不会破坏 Profile closure、共享 leaf、进程权限或高权 authority 排除。

被拒绝的替代方案

把 19 个包合成少数大包：npm dependency 按 package 解析，会把 administration、Secret、 Process 和 Execution 依赖带入 storage-only 设备，拒绝。
所有 Profile 统一抬到更大门限：掩盖 storage/adopted 回归，拒绝；只有真实加载完整 application 的能力层采用 24 MiB。
从 npm package 删除声明文件：破坏类型消费者与开发体验，拒绝；裁剪只发生在最终运行 assembly。
删除任意第三方文档、locale 或 package metadata：会产生不可审计、升级易漂移的供应链裁剪，拒绝。
让 disabled adoption eager-load 后只在业务上不执行：安装闭包和 import RSS 仍已支付，拒绝；enable gate 必须先于 authority import。

验证

十档 exact offline artifact audit 全部通过：

Profile	files	bytes	loaded modules	RSS delta bytes
edge	320	3,476,131	42	10,633,216
standalone	320	3,476,179	42	10,780,672
edge-adopted	358	4,033,157	43	10,764,288
standalone-adopted	358	4,033,241	43	10,878,976
edge-application	412	4,516,812	98	20,168,704
standalone-application	412	4,516,956	98	20,578,304
edge-ai	343	4,067,239	43	10,878,976
standalone-ai	343	4,067,299	43	10,878,976
edge-application-ai	435	5,107,992	97	20,348,928
standalone-application-ai	435	5,108,148	97	20,414,464

每档报告都包含实际/最大 files、bytes、RSS、精确 package 集合及被裁剪的内部开发文件计数。 local image 静态审计返回 findings=[]，并确认 application closure 包含 local-secret。 adopted lazy-authority 契约 8/8、TaskDefinition transaction 定向回归 13/13、local image 审计 7/7、local-sqlite 189/189 均通过；19 个 QL3 package 清理后拓扑构建和完整测试零失败，backend 956 pass/2 条件 skip/0 fail。Edge import compatible，19-importer dependency audit findings=[]；GitNexus compare-to-develop 与工作树检测均为 LOW、0 affected process。

后续约束

每次新增 production export、application capability 或 Profile package 必须重跑全部十档，不能只测 edge；
报告数字是开发机可重复审计门，不自动构成任意路由器的支持声明；
若 application import delta 接近 24 MiB，必须先给出模块级 eager closure 解释和瘦身方案，不能再次直接抬门；
physical Edge、native/init-managed startup、镜像 SBOM/漏洞和 Cluster HA 门保持独立。

6.3 KiB Raw Blame History Unescape Escape