qinglong/docs/adr/ADR-0300-worker-runtime-application-composition-ownership.md

# ADR-0300：Worker Runtime Application Composition 实现归属

- 状态：Accepted
- 日期：2026-08-09
- 关联：D-05、D-06、D-17、D-85、D-87、D-121、D-213、D-257、ADR-0126、ADR-0127、ADR-0139、ADR-0276、ADR-0296、ADR-0299

## 上下文

schema v4 根行数棘轮显示 `@qinglong/worker-runtime` 有 3 个 root source、874 个审计行。8 个审计行的 `index.ts` 是只导出
Worker certificate identity/store/renewal 的真实 package 根聚合入口；705 行的 `productionHeadlessApplication.ts` 与 159 行的
`productionWorkerApplication.ts` 则分别承担完整 Remote Execution 生命周期 composition 和产品级 Session/Capacity/共享 HTTPS
client composition。它们已有稳定的 `/production`、`/product` 公开 subpath，也由 `process/workerProcessApplication.ts` 作为
同一 Worker 部署单元的内部 composition 使用，不是 package 根职责。

这两个实现与 credential、execution、remote-execution、session 和 process 目录共享同一 package、镜像、binary、版本及故障域；
把它们拆成新 workspace package 会制造新的依赖与制品边界，却不会获得独立部署或权限生命周期。

移动前 GitNexus 显示两个文件为 LOW（Headless 2 direct/3 total、Product 1/2，均 0 process），公开启动函数为 LOW/0 process。
`ProductionWorkerHeadlessApplicationError` 为 HIGH（8 direct/14 total/0 process），`inspectUnsettled` 为 HIGH（2/6/0）；高风险来自
同一 Worker startup/drain/error 收敛链的内部密集调用，而不是产品执行流扩散。因此本批不得修改 error identity、startup
reconciliation、Session registration、certificate maintenance、drain/stop 顺序、timer 或 client ownership 语义。

## 决策

1. 将两个生产 composition 原样归入 `src/application-runtime/productionHeadlessApplication.ts` 与
   `src/application-runtime/productionWorkerApplication.ts`；Product composition 继续直接依赖同目录 Headless seam。
2. 不保留根 wrapper。`package.json` 的 `/production` 与 `/product` 直接映射嵌套编译产物；公开 package specifier、导出 symbol、
   error class identity、类型、disabled path、start/tick/stop 语义保持不变。
3. `process/workerProcessApplication.ts` 直接引用新的领域模块，避免 package 内部反向依赖根路径。package 内测试改用公开 self-reference；
   仓库根 Worker↔PostgreSQL live contract 不是 workspace importer，因此显式绑定新的嵌套 `dist` 路径。
4. `index.ts` 留在根目录并继续作为轻量公开聚合入口；`ql3-worker` binary 仍由 `process/workerProcessCli.ts` 承担，不为根文件数字移动
   真实进程入口。
5. package ledger 将 Worker Runtime 的 `rootSourceFileHardCap` 从 3 降为 1、`rootSourceLineHardCap` 从 874 降为 8；boundary
   回归冻结 source/root/nested、manifest 两个 subpath target 与旧根文件不存在。
6. 不新增 workspace package、生产依赖、数据库对象、connection、Agent、timer、listener、watcher、进程、binary 或部署单元。

## 被拒绝的方案

- **保留两个根 facade**：物理旧路径不是公开契约；wrapper 只会保留无职责的 root cap 与包内反向依赖。
- **拆出 Worker Application package**：两个 composition 不具备独立镜像、升级、权限或故障边界，会扩大 lockfile、SBOM 和小设备依赖面。
- **同时拆分 705 行 Headless lifecycle**：本批需要证明路径之外零语义变化；改动 startup/drain/certificate/lease 顺序会扩大 HIGH 风险审查面。
- **移动 `index.ts` 或 process CLI**：前者是真实轻量 package 根入口，后者是真实 executable root；移动不会改善领域职责。

## 接受条件

1. Worker Runtime 保持 32 个 source，root 3→1、874→8 个审计行，nested 29→31；workspace 保持 19 package/768 source，
   root 42→40、nested 726→728。
2. `/production`、`/product` 与 `ql3-worker` 公开契约保持；Worker 及完整 19-package clean build/test 通过。
3. 旧根源码与 clean build 旧根产物均不存在；Worker Process 与仓库 live contract 只使用新领域路径或公开 package specifier。
4. backend、依赖/边界/Edge/镜像/Worker deployment、Worker resource、十档本机制品及 Worker↔PostgreSQL 实机门通过。
5. 强制 GitNexus 不增加产品流程；HIGH 项保持原调用半径和 0 process，`detect_changes` 不出现额外受影响执行流。

## 接受证据

- package boundary schema v4 报告 Worker Runtime 为 32 source、1 root/8 root lines/31 nested；workspace 仍为 19 package、
  768 source、40 root、728 nested，`singleSourcePackages=[]`。
- Worker 132/132、完整 19-package clean build/test 与 backend 1,112（1,110 pass/2 skip/0 fail）通过；clean build 根只产生
  `index.*`，不再产生两个旧 production composition 产物。
- dependency、package boundary、Edge import、Local image、Worker deployment 与 Cluster image release 审计全部 compatible。
  Worker Edge 资源基准为 active 70,533,120 bytes、peak 70,877,184 bytes、TLS 1.3 mTLS/1 socket/3 requests，门禁通过。
- 十档本机制品门全部 compatible：基础 Edge 为 3,635,197 bytes/332 files/48 modules；最大 Standalone Application AI 为
  6,123,790 bytes/491 files/104 modules，各档 artifact/file/module/RSS 均未越界。
- PostgreSQL 18.4 Worker live contract `gates.passed=true`：证书与 credential rotation 保持同一 Session，旧证书拒绝、新证书接受，
  Run/Attempt/Lease/Artifact 完成且 runtime/ingress authority 隔离成立；运行后临时 container/volume/network 均为空。
- 强制 GitNexus 刷新为 43,318 nodes/98,527 edges/1,698 clusters/269 flows。两个文件仍为 LOW、2/3 与 1/2、0 process；
  error class 保持 8 direct/14 total/0 process，`inspectUnsettled` 保持 2/6/0，正确归入 Application-runtime 后风险分类分别由
  HIGH 收敛为 MEDIUM/LOW，没有减少或隐藏调用方。`inspectUnsettled` 仍只由 startup seam 与 drain closure 直接调用。
  `detect_changes` all 为 12 files/31 symbols，compare `develop` 为 14/34，均 low/0 affected process。