qinglong/docs/adr/ADR-0185-workspace-package-boundary-consolidation.md

# ADR-0185：Workspace Package 边界审计与最小 Profile 交付梯度

- 状态：Accepted
- 日期：2026-07-28
- 关联：RFC D-02、D-05、D-35、D-37、D-40、D-42、D-169、D-174、D-175；
  ADR-0088、ADR-0093、ADR-0179、ADR-0184

> 2026-08-01 更新：ADR-0257/D-240 supersede 本 ADR 中“所有 Profile 共用 16 MiB
> import RSS delta”的部分，并明确 npm 开发包与最终运行制品的裁剪边界。本文的
> package/authority 边界和分层 files/bytes 预算保持有效；后续 22→19 package 收敛见
> ADR-0217 与 ADR-0243。

## 背景

QingLong 3.0 当前有 22 个 workspace package。包边界在孵化阶段帮助隔离了
SQLite/PostgreSQL、常驻 runtime/短生命周期 authority、Edge/Cluster 和可选 AI，
也阻止了 legacy 根包反向进入 3.0。部分 package 只有一至三个源码文件，因此需要
确认它们是有效交付边界，还是仅把源码目录误建成 package。

workspace package 不是普通源码目录：

- 每个 package 都增加 manifest、exports、tsconfig、build/test closure 和 lockfile
  importer 维护成本；
- 错误拆分会产生没有独立消费者、产物或 authority 的线性依赖链；
- 低配设备的主要成本来自最终 Profile 产物和 native/第三方依赖闭包，不是仓库中
  package 数量本身；
- 反过来，按文件数合并可能把 Secret 写 authority、GC/destructive authority、
  POSIX Owner 代码或 application 依赖带入更小的 Edge 产物。

## 审计事实

### 1. 一文件 package 不等于无效 package

22 个 package 中只有 3 个 package 只有一个生产源码文件：

- `@qinglong/local-command-file`：161 LOC，无生产依赖，被 local-application、
  local-owner-cli 和 local-owner-maintenance 三个 package 使用；
- `@qinglong/local-identity`：327 LOC，生产只依赖 runtime-core；它让通用 credential
  authentication 不反向依赖 POSIX Owner console、keyring 或 SQLite composition；
- `@qinglong/local-secret-admin`：489 LOC，是短生命周期 Secret 明文写入/强认证/
  Policy/audit authority，刻意不被常驻 application 依赖。

三者分别满足共享依赖反转、运行时认证边界和高权限代码排除，不能按 LOC 自动合并。

### 2. Profile 线性源码链实际是独立交付梯度

从 manifest 看，`local-profile → local-adopted-profile → local-application` 各只有一个
直接生产消费者，表面像可合并的 composition chain。但 artifact audit 实际发布三个
不同层级：

```text
edge / standalone storage-only
  runtime-core + local-sqlite + local-profile

edge-adopted / standalone-adopted
  storage-only + local-admin + local-adopted-profile

edge-application / standalone-application
  adopted + command-file + secret + process + execution + local-application
```

npm dependency 是 package 级而不是 export subpath 级。若把 profile 源码改成
`local-application/profile/*`，只安装该 subpath 仍会解析 local-application 的全部
production dependencies，把 command-file、Secret、Process 和 Execution 闭包带入
storage-only 路由设备产物。把 adopted-profile 合入 application 也会消灭中间的
adoption/fence 独立产物。

因此这两个小 package 是制品裁剪边界，不是单纯代码分层。

## 决策

### 1. Package 是交付与 authority 边界，不是代码分层单位

新增或保留 workspace package 必须至少满足一项：

1. **Profile/依赖隔离**：只进入特定部署 Profile，或隔离 native/大型第三方依赖；
2. **进程/凭据隔离**：拥有独立 binary、数据库角色、Kubernetes RBAC、OS 权限、
   credential 或 destructive authority；
3. **发布边界**：需要独立制品、平台矩阵或供应链审计；
4. **依赖反转**：是被两个以上上层 package 共享的稳定叶子，合并会迫使低层依赖
   composition root；
5. **运行时安全边界**：即使源码很少，也必须证明常驻产物不能携带该 authority。

仅有“领域名称不同”“目录更整齐”“当前只有一个文件”都不能单独成为 package
理由。领域内聚继续通过目录、文件和显式 package subpath 表达。

### 2. 当前 22 个 package 保持不变

- 保留 `local-profile` 作为 storage-only Edge/Standalone 制品边界；
- 保留 `local-adopted-profile` 作为 legacy activation fence 的增量制品边界；
- 保留 `local-command-file`、`local-identity` 和 `local-secret-admin` 的共享或
  authority 边界；
- `runtime-core`、`local-sqlite` 和 `cluster-postgres` 即使文件多，也不再按领域对象
  拆成 workspace package；它们通过显式 subpath 和源码目录管理内聚，分别承担
  Profile-neutral contract、单机 storage adapter 和 Cluster storage adapter 的单一
  发布职责。

只有在 storage-only/adopted 独立产物被明确取消，或引入可证明按 subpath 裁剪
production dependency 的新制品技术后，才能重新评估 Profile 合并。

### 3. 建立 package budget

- QL3 workspace importer hard cap 继续为 22；
- 新 package 必须在 RFC/ADR 中声明满足的边界条件、目标 Profile、生产消费者、
  third-party/native dependency 变化和制品预算；
- 若不能证明新的交付/authority 边界，应优先新增现有 package 的显式 subpath；
- 超过 22 必须同一变更合并或删除至少一个既有 package，或显式修改本 ADR；
- package 数不是性能 KPI，最终仍以 Edge/Standalone/Cluster/Worker 独立产物的
  bytes、files、loaded modules、RSS 和启动门为验收依据。

### 4. Profile 资源门按真实交付层级区分

统一 4 MiB/512-file 门已经无法同时表达 storage-only、adopted compatibility 和完整
application：当前 storage-only 仍低于该门，但 adopted 在没有加载完整 application
runtime 的情况下已达到约 4.51 MB/530 files。采用以下独立上限，RSS 均保持 16 MiB：

- storage-only：4 MiB / 512 files；
- adopted compatibility：5 MiB / 576 files；
- application：5 MiB / 640 files；
- application + AI：6 MiB / 768 files。

这不是把同一个失败门静默抬高：artifact report 必须输出 Profile 名、精确 package
集合和实际上限，storage-only 的路由设备门完全不变；adopted 仍比 application 少
64 个文件预算，且只用于需要 legacy write fence 的兼容部署。

## 不采用方案

### 将 Profile 两个小包合入 local-application

源码移动本身风险低，但会因 package-level production dependencies 扩大 storage-only
和 adopted 制品，直接违背路由设备最小依赖目标。

### 按 LOC 或文件数自动合并

会把 Secret admin、Owner maintenance 等高权限代码带入常驻产物，也无法识别共享
叶子造成的依赖反转。

### 每个领域对象一个 package

会把 runtime-core 和 storage adapter 拆成大量 importer，增加 lockfile、构建、
发布和供应链成本，但没有新增运行时隔离。

### 把全部本机包合成 `@qinglong/local`

会让 storage-only、adopted、application、Owner CLI、maintenance/destructive
authority 和 Secret 写 authority 共享同一发布单元，破坏当前可执行的 dependency/
source boundary。

## 验收证据

- GitNexus 对六个 Profile/adopted bootstrap 及四个内部 helper 的 upstream impact
  均为 LOW，0 条执行流程；这说明源码移动容易，但不能证明制品合并合理；
- manifest 审计确认 3 个一文件 package 的消费者和 production dependency 边界；
- artifact assembly 确认 storage-only、adopted、application 和 AI on/off 是不同
  package chain，而不是同一制品的重复 wrapper；
- storage-only 门通过：edge/standalone 为 4,062,246/4,062,306 bytes、486 files、
  40 loaded modules；adopted 独立门通过：4,510,432/4,510,516 bytes、530 files、
  43 loaded modules；
- D-174 后四种 application 产物门继续通过：非 AI 4,915,362–4,915,506 bytes、
  615 files、90 loaded modules；AI 5,593,183–5,593,339 bytes、659 files、
  89 loaded modules；
- 本轮没有保留任何 Profile 源码移动、manifest、lockfile 或 importer package
  hard-cap 变更，最终代码拓扑仍为 22 package；只新增 adopted 专属制品预算。

## 后续

每增加 5 个 D-series vertical slice，或 QL3 package 数拟超过 22 时重新生成相同
审计表：源码文件/LOC、生产消费者、依赖闭包、exports/binary、authority 和实际
Profile 制品归属。合并候选必须同时证明源码内聚和制品/authority 不回归。