qinglong/docs/adr/ADR-0328-runtime-core-workflow-administration-domain-ownership.md

ADR-0328：Runtime Core Workflow Administration 领域归属

• 状态：Accepted
• 日期：2026-08-10
• 关联 RFC：QL-RFC-0001 D-08、D-09、D-12、D-70、D-85、D-87、D-207、D-212、D-213、D-250、D-251、D-257
• 关联 ADR：ADR-0270、ADR-0276、ADR-0277、ADR-0282、ADR-0283、ADR-0284、ADR-0285、ADR-0286、ADR-0327

背景

ADR-0321 至 ADR-0327 已明确：workspace package 表达可部署、authority、依赖、adapter、multi-consumer 或供应链 边界，package-private 目录表达同一发布单元内的领域 ownership。继续审计 @qinglong/runtime-core 时发现，公开 subpath 背后的 pluginPackageWorkflowAdministration.ts 虽然不持有数据库或网络 authority，但 1,604 行单文件同时定义并校验：

1. Workflow admission 与 repository contract；
2. cancellation contract、result 和稳定错误；
3. Run inspection command/result；
4. Run history 的 page/cursor/item/result；
5. StepRun page/cursor/item/result；
6. RunEvent sequence page/item/result；
7. 共享 exact-shape、identity、Package、resource、fence、actor/audit binding codec。

这些 contract 都属于一个稳定的 plugin-package-workflow-administration public subpath，不应拆成新 workspace package 或多个 public subpath；但继续平铺会让五类读取协议、两类 mutation 和共享安全 codec 无法独立演进、审阅和测试。

编辑前对原文件全部 38 个 class、function 和 method（包括 7 个 repository method 与 4 个 constructor）执行 GitNexus upstream impact。三个稳定 error、exactKeys 以及 admission/inspection/list repository method 为 HIGH，其中两个冲突 错误与 admission method 影响 1 条执行流；共享 subject/fence/identifier helper 为 MEDIUM，其余为 LOW，无 CRITICAL。 本轮仅移动 ownership，不修改任何公开 contract 或 normalization 语义。

决策

保持一个 @qinglong/runtime-core package、一个 public subpath 和 7 行 facade，在原 Workflow 目录内建立 package-private 领域目录：

pluginPackageWorkflowAdministration.ts        # stable public facade
plugin-package-workflow-administration/
├── contracts.ts                              # all public types, schemas and budgets
├── errors.ts                                 # four stable runtime error identities
├── support.ts                                # shared exact-shape/identity/fence codec
├── runInspection.ts                          # one Run inspection normalization
├── runList.ts                                # newest-first Run keyset page
├── stepRunList.ts                            # ordered StepRun keyset page
├── runEventList.ts                           # contiguous RunEvent sequence page
└── mutation.ts                               # admission and cancellation normalization

contracts.ts 只使用 type-only domain imports，避免仅消费接口时加载实现。support.ts 是 package-private 共享 codec， 不从 facade 或 package manifest 导出。五个 operation owner 只能依赖 contracts、errors、support 和各自必要的 Run/Security/ Workflow plan contract；它们不取得 filesystem、process、timer、network、SQLite 或 PostgreSQL authority。

facade 只 re-export 原有公开集合。26 个 runtime export 与 owning module 保持同一个 object，包括四个 error constructor、 四个 schema、六个 page budget、cancellation status 和十一项 normalizer；没有新增 public subpath、workspace package、 production dependency、进程或部署单元。

本轮不修改 exact keys、identifier/Package/resource pattern、page limit、cursor order、Run/StepRun/Event 状态约束、连续 sequence、low-sensitive projection、strong User、allowed audit、authentication/fence binding、admission time binding、 cancellation reason/result、错误 code/message 或 repository method shape。

小设备与集群影响

所有本机 Profile 都携带裁剪后的 Runtime Core 文件，因此目录拆分为每档增加固定 5,801 bytes 和 8 个物理 JavaScript 文件；loaded modules 完全不变：Edge/Standalone 49、Adopted 50、Application 116、AI 50、Application AI 115。 最小 Edge 产物为 3,650,344 bytes，仍低于 4 MiB hard cap；没有新增常驻连接、Pool、timer、watcher、listener、缓存 或后台进程。

Cluster 继续通过原 public subpath 共享同一纯 contract/normalizer，并使用独立 PostgreSQL repository、TLS、RBAC、quota 和多副本 transport。dependency/deployment audit 未出现新依赖或 authority。本轮没有 SQL、migration、PostgreSQL、 Kubernetes resource 或部署拓扑变化，因此虽已获准，仍不重复执行与本次纯 Runtime Core ownership 重构无关的 PostgreSQL HA Docker 门。

被否决方案

1. 为 inspection/list/event/mutation 各建 workspace package：没有独立部署、依赖或 authority 边界，会制造微包。
2. 为每个 normalizer 建文件：共享协议会退化成一函数一文件，增加导航成本而不提升 ownership。
3. 新增五个 public subpath：扩大长期兼容面，并允许消费者绕过统一 Workflow Administration contract。
4. 公开 support.ts：会把内部 exact-shape helper 变成可依赖 API，阻碍未来实现替换。
5. 趁拆分改变 page budget、regex 或 error mapping：会把结构重构与协议版本变更混在一起。
6. 继续保留 1,604 行单文件：读取、mutation 和共享安全 codec 继续互相遮蔽，拒绝。

验收证据

• facade 1,604→7 行；contracts 265、errors 41、support 86、Run inspection 228、Run list 282、StepRun list 339、 RunEvent list 254、mutation 206 行，总计 1,708 行；新增行主要是显式 import/export ownership。
• 26/26 runtime export identity 相同，无 missing、extra 或 identity drift；Runtime Core 445/445。
• 完整 16-package clean topology build/test 退出 0；Cluster PostgreSQL、Local SQLite、Local Admin、Owner CLI 和 Local Application 的 Workflow 调用链全部通过，外部 PostgreSQL/S3 与 Linux /proc 条件项保持显式 skip。
• package boundary 为 16 package、871 source、25 root、846 nested，singleSourcePackages=[]、 shallowSourcePackages=[]、findings 为空；Runtime Core 为 132 source、1 root public export/131 nested。Edge import 为 121 modules 且无 forbidden；Cluster dependency/deployment 全部 compatible/findings 为空。
• 串行十档 artifact 全部通过。Edge/Standalone 3,650,344/3,650,380 bytes、350 files、49 modules；Adopted 4,270,853/4,270,913 bytes、402 files、50 modules；Application 4,768,702/4,768,822 bytes、461 files、116 modules；AI 5,045,655/5,045,703 bytes、429 files、50 modules；Application AI 6,164,079/6,164,211 bytes、 540 files、115 modules。相对 ADR-0327 每档固定 +5,801 bytes/+8 files、loaded modules +0。
• 制品门不能并行共享构建目录：一次并行尝试因相互清理 dist 出现无效 .d.ts 编译结果，已废弃该批证据并按十档 串行重跑全部通过。
• 最终强制索引为 44,160 nodes/100,542 edges/1,727 clusters/274 flows。post-impact 中 invalid error 为 CRITICAL （32 direct/32 total/0 process），两个冲突 error 为 HIGH（10/29/1 与 22/31/1），exactKeys 为 HIGH （16/16/0）；五个 operation 代表 normalizer 为 LOW。显式内部引用使共享错误的 blast radius 更完整，没有新增行为。
• detect_changes all/compare develop 仍只映射已跟踪 Legacy baseline 的 12/31 与 14/34、low/0 process；当前 QL3 孵化树尚未完整进入 Git baseline，因此它只作补充，不能替代逐 symbol impact、强制索引、完整测试与制品门。

后续约束

Workflow Administration 的公开兼容面继续由单一 facade 管理。contracts/errors 不得取得运行 authority；support 不得 公开；各 operation owner 不得互相调用或修改其他 operation 的预算。新增 use case 只有在具备完整 command/result、独立 审计语义和明确分页/状态不变量时才建立领域 owner，不按函数数量或 LOC 机械拆分。