qinglong/docs/adr/ADR-0337-plugin-package-prompt-execution-domain-ownership.md

ADR-0337：Plugin Package Prompt Execution 领域归属

• 状态：Accepted
• 日期：2026-08-10
• 关联 RFC：QL-RFC-0001 D-05、D-06、D-17、D-37、D-75、D-85、D-87、D-157、D-161、D-213、D-243、D-244、D-257
• 关联 ADR：ADR-0177、ADR-0276、ADR-0326、ADR-0332、ADR-0333、ADR-0336

背景

@qinglong/ai 的 prompt/pluginPackagePromptExecution.ts 有 1,199 行，同时承担：

1. execution plan、output intent、admission/finalization receipt、repository port 与稳定错误契约；
2. exact-shape、identity、digest、timestamp、大小和 canonical value 的 fail-closed 校验；
3. Prompt definition、参数、渲染、模型请求、output intent 与完整 execution plan 的规划和 normalization；
4. admission/finalization identity、receipt codec，以及初始 Run、RunEvent、StepRun mutation durable bundle 的构造。

这些职责共同定义一个 Plugin Package Prompt execution protocol：先把 publication 和瞬态输入固化为不含明文的 execution plan，再由 Local SQLite 或 Cluster PostgreSQL adapter 原子 admission，最后从精确 ModelInvocation 证据完成 finalization。它没有 独立部署、依赖、权限主体、生产 consumer 或供应链生命周期，因此不能因为文件较大再新增 workspace package；但继续把公开 contract、纯规划算法、durable receipt codec 和 Run/StepRun 初始事实构造混在一个文件中，也不利于审阅 digest 与持久化边界。

编辑前对 37 个 function/class 和 5 个 repository port method 逐一执行 GitNexus upstream impact：20 CRITICAL、14 HIGH、 8 LOW。PluginPackagePromptAdmissionUnavailableError 为 34 direct/92 total/1 process，invalid 为 17/43/1， normalizePluginPackagePromptExecutionPlan 为 9/29/1；唯一受影响流程是 Local Owner CLI 的 Plugin Package Prompt command runner。已在编辑前告警，并把本批限定为语义等价的 ownership 移动，不调整字段次序、digest domain、大小预算、渲染、identity 推导或 admission/finalization 时序。

决策

保留一个 @qinglong/ai package、原 prompt/pluginPackagePromptExecution 导入路径和显式 public facade。在同一 Prompt 领域建立 package-private owner 目录：

pluginPackagePromptExecution.ts             # 44-line stable explicit facade
plugin-package-prompt-execution/
├── contracts.ts                            # schemas, public ports, requests/results and stable errors
├── validation.ts                           # exact values, identity, digest, time and size validation
├── plan.ts                                 # definition/parameter/render/output/plan canonical preparation
└── durableEvidence.ts                      # admission/finalization receipts and Run/StepRun durable bundle

依赖方向固定为 contracts <- validation <- plan，durableEvidence 只依赖 contract、validation、plan 和既有 Runtime Core domain contract；它不得取得 SQLite、PostgreSQL、Pool 或 provider I/O authority。根 facade 显式逐项转发原 25 个 runtime export 及既有 type surface，不以 wildcard 暴露内部校验器、canonical shape 或 digest input。

execution/definition/admission/finalization digest domain、JSON field/order、exact-key validation、64 KiB 参数值、32 KiB plan、 16 KiB receipt 上限、legacy 缺失 output 的 exact live-only 语义、字符串替换渲染、identity 推导、瞬态 AbortSignal 排除、 Run/StepRun 初始 version/event facts、admission/finalization receipt counter 和稳定 error code/message 均保持。本轮不借目录化 统一 SQLite/PostgreSQL 事务实现，也不改变 provider 调用边界。

四个 owner 文件分别是 contracts 244、validation 126、plan 515、durable evidence 375 行。没有按每个 digest、receipt、 normalizer 或 repository method 建立单文件；最大文件 515 行，仍是一组共同变化的完整 planning protocol。

小设备与集群影响

不启用 AI 的 Edge、Standalone、Adopted 与 Application 六档制品逐字节、逐文件不变：最小 Edge 仍为 3,658,234 bytes、358 files、49 loaded modules。启用 AI 的四档因一个旧编译文件变成 facade 加四个 owner 编译文件，统一 增加 9,560 bytes/4 files，loaded modules 不变：Edge/Standalone AI 为 5,107,407/5,107,455 bytes、487 files、50 modules；Edge/Standalone Application AI 为 6,225,831/6,225,963 bytes、598 files、115 modules。没有新增 workspace package、生产 dependency、连接、timer、watcher、listener、线程或常驻对象；未启用 AI 的低配路由设备不承担目录化成本。

Cluster 继续使用同一个 @qinglong/ai contract 和既有 PostgreSQL admission repository，没有新增 Pool、角色、Pod、Service、 sidecar 或 Kubernetes resource。PostgreSQL 18.4 arm64 physical-streaming HA 门通过 remote_apply、timeline 1→2、旧主 fencing、pg_rewind 后只读同步 rejoin；Prompt admission/finalization 的 exact replay、同步复制、promotion 存活、Policy fence、 content-free durable record 和 output Artifact 原子提交门全部为 true，最终 gates.passed=true。

被否决方案

1. 新增 Prompt Execution workspace package：没有独立部署、重依赖、authority 或多消费者边界，只会扩大 importer、packlist 与 SBOM。
2. 继续保留 1,199 行文件：公开协议、纯规划和 durable evidence 无法作为独立审查单元。
3. 按每个 digest/normalizer/receipt 一文件：会制造一操作一文件，并割裂共享 canonical field/order 不变量。
4. 把 Local/PostgreSQL repository 一并移入 owner 目录：会把纯协议与双方言的事务、连接和错误映射 authority 混合。
5. 直接公开四个 owner subpath：会把内部层次固化成兼容承诺，并允许 consumer 绕过稳定 facade。
6. 趁移动修改渲染或统一 legacy output：会改变 plan digest 和 durable replay，必须另立 ADR 与迁移协议。

验收证据

• public facade 1,199→44 行；owner 为 244/126/515/375 行，总计 1,304 行，最大 515；没有一方法一文件。
• 编译后的 facade 仍只有原 25 个 runtime export；所有 type export 由原路径生成，内部 validation/canonical shape 未公开。
• @qinglong/ai check 通过；AI package 212 项为 209 pass/3 条件 skip/0 fail；完整 16-package clean build/test 在允许 loopback TLS listener 的环境退出 0。
• package boundary、Edge import、Cluster dependency、Cluster deployment 四项审计全部 compatible；workspace 仍为 16 package、929 source、25 root/904 nested，singleSourcePackages=[]、shallowSourcePackages=[]。AI 为 127 source、1 root/126 nested，Edge imported modules 仍为 121。
• 十档 artifact 均 compatible；非 AI 六档精确不变，AI 四档 +9,560 bytes/+4 files/+0 loaded modules。
• PostgreSQL HA Docker 门退出 0，旧主 fencing、promotion、rejoin、Prompt durable protocol 和最终 gate 全部通过。
• git diff --check 通过；GitNexus 强制重建为 44,443 nodes/101,380 edges/1,739 clusters/296 flows。post-impact 中 plan preparation 为 LOW（1 direct/2 total/1 process），plan normalization 为 CRITICAL（9/29/1），admission bundle 为 LOW（4/16/1），receipt digest 为 HIGH（2/10/0）；稳定错误仍因双方言 adapter 共同依赖显示 CRITICAL，但没有新增 execution flow，唯一流程仍是原 Local Owner Prompt command runner。
• detect_changes all 为 12 files/31 symbols/0 process/low，compare develop 为 14/34/0/low；当前 QL3 孵化树尚未完整进入默认分支索引，因此 detect result 只作 Git 基线补充。工作区无 staged change。

后续约束

contracts.ts 不取得 I/O authority；validation.ts 不拥有业务流程；plan.ts 不写 durable state；durableEvidence.ts 不打开 数据库或调用 provider。新增字段/schema version 必须同时评审 canonical digest、双方言 durable replay、legacy plan 和制品预算； 新增 execution operation 按共同变化原因归入现有 owner，不能自动增加文件或 package。只有出现独立部署、独立权限主体、显著可选 依赖、多个生产 consumer 或可测 artifact 裁剪价值时，才重新评估 workspace package 边界。