# ADR-0332：Local Plugin Package Prompt Admission Repository 领域归属

- 状态：Accepted
- 日期：2026-08-10
- 关联 RFC：QL-RFC-0001 D-05、D-06、D-17、D-37、D-85、D-87、D-157、D-161、D-213、D-243、D-244、D-257
- 关联 ADR：ADR-0168、ADR-0170、ADR-0171、ADR-0260、ADR-0261、ADR-0276、ADR-0330、ADR-0331

## 背景

ADR-0330 与 ADR-0331 已把双方言 Model Invocation repository 从千行级单文件收敛为同包领域目录。继续审计
`@qinglong/ai` 的 Prompt 执行链时，发现公开 `local-plugin-package-prompt-admission-storage` subpath 背后的
`prompt/localPluginPackagePromptAdmissionRepository.ts` 有 1,261 行，其中一个 repository class 同时拥有：

1. SQLite 单连接队列、64 pending hard cap、错误映射与 identity/row/JSON codec；
2. Run、RunEvent、model StepRun、StepRunMutation 与 Prompt Admission 写入；
3. admission plan/receipt 查询、反序列化和完整 durable evidence 复验；
4. active publication、installation、lifecycle、quarantine 与 materialized Prompt 的当前目标复验；
5. feature fence、mutation guard、exact replay 与 `BEGIN IMMEDIATE` admission transaction；
6. Completion/Resolution terminal evidence 解析、父 Run CAS、final event 与 finalization receipt 原子提交；
7. admission/finalization 的四类读取和公开 repository composition。

这些能力共同形成一个 Local SQLite Prompt Admission adapter，共享同一 `DatabaseSync`、同一 Model Invocation operation
authority、同一 Run/StepRun 事实链和事务边界，不具备拆成新 workspace package、进程或公开 subpath 的独立价值；但继续
平铺会让资源 authority、admission record、目标复验、finalization 生命周期和公开 delegation 共享完整文件上下文。

编辑前对文件内 35 个 function/class/method 逐一执行 GitNexus upstream impact：31 个 LOW、4 个 MEDIUM、0 个 HIGH/
CRITICAL。MEDIUM 为 identity、row text、canonical JSON 和单连接 queue；queue 为 1 direct/47 impacted/0 process，公开
repository 为 LOW、2 direct/2 impacted/2 process。该结果允许等价 ownership 拆分，但要求保留队列上限、事务、exact replay、
durable evidence 和 crash recovery 语义。

## 决策

保持一个 `@qinglong/ai` package、一个 public subpath 和 4 行稳定 facade，在既有 Prompt 领域内建立 package-private owner
目录：

```text
localPluginPackagePromptAdmissionRepository.ts          # stable public facade
local-plugin-package-prompt-admission-repository/
├── authority.ts                                        # queue、validation、row/JSON 与 error mapping
├── admissionRecords.ts                                 # admission durable reads/writes/evidence codec
├── admissionOperation.ts                               # target guard、replay 与 admission transaction
├── finalizationOperations.ts                           # terminal evidence、receipt 与 finalization transaction
└── repository.ts                                       # stable public class and narrow delegation
```

不按六个公开 method 建六个文件，也不把 64 pending queue 单独升级为 package。公开 class 保持原 constructor 和六个 method
signature；`LocalPluginPackagePromptAdmissionMutationGuard` 仍是 type-only export，runtime module 仍只含原 class。

`authority.ts` 继续复用注入的 `LocalModelInvocationOperationAuthority`；只在调用方直接传入 `DatabaseSync` 时创建原有
process-local queue。所有 read/admit/finalize operation 仍进入同一 queue，并使用同一 client，不创建第二个连接、timer、
watcher、cache 或后台任务。

Admission 仍按 existing replay → feature fence → mutation guard → current publication/materialization guard → Run/Event/Step/
Mutation/Admission writes 的原次序在一个 `BEGIN IMMEDIATE` 中提交。Finalization 仍按 existing replay → feature fence →
admission/evidence read → counter fence → Run CAS → final event → finalization receipt 的原次序提交。异常仍只在已开启事务时
best-effort rollback，并保留原 fail-closed error。

本轮不修改 SQL text、table/index/migration、row projection、JSON/digest、identity、event/mutation sequence、Run/StepRun
状态机、Prompt target guard、feature activation、mutation guard、Completion/Resolution 解释、error code/message 或 transaction
mode。PostgreSQL Prompt Admission adapter 保持独立，下一批按同一原则审计，不强行共用双方言 SQL。

## 小设备与集群影响

不含 AI 的 Edge、Standalone、Adopted 与 Application Profile 制品逐字节不变，最小 Edge 仍为 3,658,234 bytes、358
files、49 loaded modules。启用 AI 的四档各固定增加 2,847 bytes 和 5 个物理 JavaScript 文件：Edge/Standalone AI 为
5,083,394/5,083,442 bytes、461 files、50 modules；Edge/Standalone Application AI 为
6,201,818/6,201,950 bytes、572 files、115 modules，仍低于对应 5/6 MiB hard cap。运行时 loaded modules 增量为 0，
没有新增常驻对象、连接、timer、watcher、listener 或网络 authority。

Cluster PostgreSQL Prompt Admission repository、schema、migration、Pool、ACL、Pod、Service 与部署拓扑均未修改。完整 package
门仍覆盖 Cluster 包，Cluster dependency/deployment audit 均 compatible；上一批 ADR-0331 已在同一工作树基线上重跑并通过
PostgreSQL 18.4 physical HA，本批不因纯 Local owner 移动重复执行 Docker failover。

## 被否决方案

1. **把 admission/finalization 拆成新 workspace package**：二者共享同一 SQLite queue、数据库事务和部署闭包，会制造发布碎片。
2. **继续保留 1,261 行 repository class**：资源 authority、记录 codec、目标复验和两个事务生命周期无法独立审阅。
3. **按六个公开 method 一方法一文件**：四个 read method 共享相同 admission evidence，两个 mutation method 各自拥有完整事务。
4. **公开内部 record/operation subpath**：会允许调用方绕过 queue、feature fence、target guard 与统一错误映射。
5. **给 Prompt adapter 创建独立 SQLite client**：会破坏 AI feature 与 Model Invocation 共用的串行 authority。
6. **与 PostgreSQL adapter 合并为条件 SQL/ORM**：会隐藏双方言的事务、锁、row type、错误与 HA 差异。
7. **趁拆分修改 SQL、digest 或状态机**：会把 ownership 重构与协议变化混批，无法可靠归因。

## 验收证据

- facade 1,261→4 行；authority 151、admission records 441、admission operation 221、finalization operations 471、
  repository 116 行，总计 1,404 行；最大 owner 471 行，没有一方法一文件。
- public runtime module 只含 `LocalPluginPackagePromptAdmissionRepository`，与 owning module 为同一 class object；mutation
  guard 仍为 type-only export，无 missing、extra 或 runtime identity drift。
- 定向 admission/execution/crash 测试 13/13；Edge/Standalone 各 10 个 admission/finalization crash point，共 20 场景，
  16 个 commit 前窗口无部分事实、4 个 commit 后窗口 exact replay，`integrity_check`/foreign key check 均通过。
- AI package 212 项为 209 pass/3 条外部 PostgreSQL 条件 skip/0 fail；完整 16-package clean topology build/test 在允许
  loopback TLS/mTLS 的环境退出 0。
- package boundary 为 16 package、903 source、25 root、878 nested，`singleSourcePackages=[]`、
  `shallowSourcePackages=[]`、findings 为空；AI 为 101 source、1 root public export/100 nested。Edge import 仍为 121
  modules，Cluster dependency/deployment 均 compatible。
- 十档串行 artifact 全部 compatible；非 AI 六档相对 ADR-0331 精确不变，AI 四档固定 +2,847 bytes/+5 files、loaded
  modules +0。
- 强制索引为 44,319 nodes/101,102 edges/1,728 clusters/296 flows。post-impact 中公开 repository 为 LOW
  （3 direct/3 total/2 process），admit/finalize operation 均 LOW（1 direct/1 total/0 process）；共享 identity、row text、
  canonical JSON、queue 和 admission lookup 为 MEDIUM，最高 8 direct/16 total/1 process，无 HIGH/CRITICAL。
- `detect_changes` all/compare `develop` 只作为 Git 基线补充；当前 QL3 孵化树尚未完整进入默认分支索引，因此不能替代逐
  symbol impact、强制索引、完整测试、crash matrix 与制品门。

## 后续约束

公开 repository 只负责稳定 interface implementation、输入 normalization 与 delegation，不重新吸收 SQL、codec 或事务
body。`authority.ts` 不取得业务决策；`admissionRecords.ts` 不自行 enqueue/开事务；`admissionOperation.ts` 必须保持 target
guard 与 admission writes 同事务；`finalizationOperations.ts` 必须保持 terminal evidence、Run CAS、event 与 receipt 同事务。
新增能力按 admission record、admission transaction、finalization lifecycle 的共同变化原因聚合，不按 method 数、LOC 或
schema 名机械建文件或 package。