qinglong/docs/adr/ADR-0333-postgresql-plugin-package-prompt-admission-repository-domain-ownership.md

ADR-0333：PostgreSQL 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-0331、ADR-0332

背景

ADR-0332 已把 Local SQLite Prompt Admission repository 从千行级单文件收敛为同包领域目录。继续处理其 Cluster 对应实现 时，发现公开 postgres-plugin-package-prompt-admission-storage subpath 背后的 prompt/postgresPluginPackagePromptAdmissionRepository.ts 有 1,257 行，其中一个 repository class 同时拥有：

1. SQLSTATE/constraint/error mapping、identity、canonical JSON、JSONB、boolean、bigint 与 nullable row codec；
2. admission/finalization query、plan/receipt 反序列化和完整 durable evidence 复验；
3. Run、RunEvent、model StepRun、StepRunMutation 与 Prompt Admission 写入；
4. SECURITY DEFINER admission snapshot、publication/materialized Prompt 精确复验与 mutation guard；
5. Completion/Resolution terminal evidence、父 Run CAS、final event 与 finalization receipt；
6. Pool checkout/release、SERIALIZABLE、transaction-local timeout、rollback 与 serialization/deadlock retry；
7. admission/finalization 四类读取和公开 repository composition。

这些能力共同形成一个 PostgreSQL Prompt Admission adapter，共享同一注入 Pool、同一 transaction client、同一 Run/StepRun 事实链、snapshot function 与 append-only ACL，不具备拆成新 workspace package、进程或公开 subpath 的独立部署价值；但继续 平铺会让错误/row authority、durable records、admission snapshot、finalization 生命周期和资源事务共享完整文件上下文。

编辑前对文件内 37 个 function/class/method 逐一执行 GitNexus upstream impact：29 个 LOW、7 个 MEDIUM、1 个 HIGH、 0 个 CRITICAL。HIGH 为统一 unavailable（17 direct/26 impacted/0 process）；公开 repository 为 LOW、4 direct/6 impacted/0 process。该结果要求集中保留错误语义，并通过真 PostgreSQL HA、COMMIT-response-loss、全包与制品门验证，不能 借 ownership 重构改写 SQL、ACL 或事务协议。

决策

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

postgresPluginPackagePromptAdmissionRepository.ts       # stable public facade
postgres-plugin-package-prompt-admission-repository/
├── authority.ts                                        # SQLSTATE、validation、JSONB/row 与 error mapping
├── transaction.ts                                      # Pool client、timeout、retry、commit/rollback lifecycle
├── admissionRecords.ts                                 # admission durable reads/writes/evidence codec
├── admissionOperation.ts                               # snapshot guard、replay 与 admission transaction body
├── finalizationOperations.ts                           # terminal evidence、receipt 与 finalization transaction body
└── repository.ts                                       # stable public class and narrow delegation

不按六个公开 method 建六个文件，也不把 61 行 transaction owner 升级为独立 package。公开 class 保持原 constructor 和六个 method signature；PostgresPluginPackagePromptAdmissionMutationGuard 仍是 type-only export，runtime module 仍只含原 class。

所有 mutation 仍通过注入的唯一 PostgresPool 获取 fresh client；runTransaction 继续统一执行：

1. BEGIN ISOLATION LEVEL SERIALIZABLE；
2. transaction-local statement timeout 5s、lock timeout 2s、idle-in-transaction timeout 5s；
3. operation body 与 COMMIT；
4. 失败后的 best-effort ROLLBACK；
5. 仅 40001/40P01 最多三次 fresh-client retry；
6. 每次 attempt 都在 finally release client。

Admission 仍按 existing replay → mutation guard → SECURITY DEFINER snapshot → publication/materialized resource verification → Run/Event/Step/Mutation/Admission writes 的原次序提交。Finalization 仍按 existing replay → admission/evidence read and lock → counter fence → Run CAS → final event → finalization receipt 的原次序提交。

本轮不修改 SQL text、table/index/migration、SECURITY DEFINER function、role/ACL、row projection、JSON/digest、identity、event/ mutation sequence、Run/StepRun 状态机、mutation guard、Completion/Resolution 解释、error code/message、transaction isolation、 timeout、retry 次数或 Pool 配置。PostgreSQL 与 SQLite 继续是独立 adapter，不引入条件 SQL/ORM 共享层。

小设备与集群影响

不含 AI 的 Edge、Standalone、Adopted 与 Application Profile 制品逐字节不变，最小 Edge 仍为 3,658,234 bytes、358 files、49 loaded modules。启用 AI 的四档各固定增加 4,711 bytes 和 6 个物理 JavaScript 文件：Edge/Standalone AI 为 5,088,105/5,088,153 bytes、467 files、50 modules；Edge/Standalone Application AI 为 6,206,529/6,206,661 bytes、578 files、115 modules，仍低于对应 5/6 MiB hard cap。运行时 loaded modules 增量为 0， 没有新增路由设备常驻对象、连接、timer、watcher、listener 或网络 authority。

Cluster 仍使用原 Pool、schema、migration、runtime role 与 deployment topology。真实 PostgreSQL 18.4 arm64 physical-streaming HA 门重新执行并通过：remote_apply、timeline 1→2、旧主 fencing、pg_rewind 后只读同步 rejoin、AI/Prompt 事实跨晋升 存活、COMMIT response loss 收敛，最终 gates.passed=true。没有新增 Pool、Pod、Service、Kubernetes resource、数据库 角色或故障转移权威。

被否决方案

1. 把 admission/finalization/transaction 拆成新 workspace package：它们共享同一 Pool、schema、ACL 与部署闭包，会制造发布碎片。
2. 继续保留 1,257 行 repository class：row/error、记录、snapshot、两个事务生命周期和资源管理无法独立审阅。
3. 按六个公开 method 一方法一文件：四个 read method 共享 durable evidence，两个 mutation method 各拥有完整事务。
4. 公开内部 record/operation/transaction subpath：会允许调用方绕过 timeout、retry、snapshot guard 与统一错误映射。
5. 给每个 operation 新建 Pool 或长期持有 client：会扩大 Cluster 连接预算并破坏 attempt 级释放与失败隔离。
6. 与 SQLite adapter 合并为通用 SQL/ORM 层：会隐藏隔离级别、snapshot function、JSONB/bigint、SQLSTATE 与 HA 差异。
7. 趁拆分修改 migration、ACL、SQL 或状态机：会把 ownership 与协议/安全/部署变化混批，无法可靠归因。

验收证据

• facade 1,257→4 行；authority 125、transaction 61、admission records 446、admission operation 158、finalization operations 439、repository 114 行，总计 1,347 行；最大 owner 446 行，没有一方法一文件。
• public runtime module 只含 PostgresPluginPackagePromptAdmissionRepository，与 owning module 为同一 class object；mutation guard 仍为 type-only export，无 missing、extra 或 runtime identity drift。
• Cluster Prompt 定向门 6 pass/1 条外部 PostgreSQL URL 条件 skip；AI package 212 项为 209 pass/3 条件 skip/0 fail； 完整 16-package clean topology build/test 在允许 loopback TLS/mTLS 的环境退出 0。
• PostgreSQL HA Docker 门退出 0，证明 PostgreSQL 18.4 arm64 physical streaming、timeline promotion/rewind、旧主 fence、 AI/Prompt durable facts 与 response-loss convergence；四项 package boundary、Edge import、Cluster dependency、Cluster deployment audit 均 compatible。
• package boundary 为 16 package、909 source、25 root、884 nested，singleSourcePackages=[]、 shallowSourcePackages=[]、findings 为空；AI 为 107 source、1 root public export/106 nested。Edge import 仍为 121 modules。
• 十档串行 artifact 全部 compatible；非 AI 六档相对 ADR-0332 精确不变，AI 四档固定 +4,711 bytes/+6 files、loaded modules +0。
• 强制索引为 44,340 nodes/101,155 edges/1,731 clusters/296 flows。post-impact 中公开 repository 为 LOW （4 direct/7 total/0 process），admit/finalize operation 为 LOW（各 1/1/0），transaction runner 为 LOW（2/2/0）。 统一 unavailable 为 HIGH（17/29/0），mapStorageError 为 HIGH（5/8/0），但均集中在 package-private authority； JSON/row/admission lookup 为 MEDIUM，无跨执行流扩散。
• detect_changes all/compare develop 只作为 Git 基线补充；当前 QL3 孵化树尚未完整进入默认分支索引，因此不能替代逐 symbol impact、强制索引、完整测试、HA 与制品门。

后续约束

公开 repository 只负责稳定 interface implementation、输入 normalization 与 delegation，不重新吸收 SQL、codec 或事务 body。authority.ts 集中保留错误和 row/JSON 语义，不取得业务决策；admissionRecords.ts 不自行 checkout Pool 或开事务； admissionOperation.ts 必须保持 snapshot guard 与 writes 同事务；finalizationOperations.ts 必须保持 evidence lock、Run CAS、event 与 receipt 同事务；transaction.ts 只拥有 client 生命周期、timeout 与 retry，不取得业务重放判断。新增能力按 records、admission、finalization、transaction 的共同变化原因聚合，不按 method 数、LOC 或 schema 名机械建文件或 package。