qinglong/docs/adr/ADR-0275-authenticated-cluster-plugin-package-prompt-product-entry.md

# ADR-0275：受认证的 Cluster Plugin Package Prompt 产品入口

- 状态：Accepted
- 日期：2026-08-04
- 关联：D-157、D-207、D-243、D-252、D-255、ADR-0260、ADR-0261、ADR-0271、ADR-0274

## 上下文

Cluster AI composition 已能显式挂载 Prompt execution route、PostgreSQL admission/finalization、
Model Gateway、projected Secret 和可选加密输出；但现有 v1 transport 仍要求 caller 提供
`publicationDigest`，并把 API admission 得到的 Subject/Policy fence 带入 AI repository。Prompt
admission snapshot 会复验 publication 与 RoleBinding fence，却没有在同一 SERIALIZABLE transaction
重新锁定 API credential、完整 `run.start + model.invoke + secret.use` 语义和 allowed SecurityAudit。

这意味着 route 已“认证”，但尚未成为完整产品 authority：caller 仍选择 generation，credential 可在
HTTP authorization 与 Run commit 之间撤销，transport allowed audit 与产生外部模型费用的 admission
不是同一个提交事实。另建 Prompt service、listener 或 Pool 会增加集群运维面，也会诱导本机 Profile
复用错误依赖。

## 决策

1. 保留既有 AI-enabled `cluster-control` process、TLS listener、authentication shield、route registry 和
   AI PostgreSQL Pool；不新增 package、service、port、Pool、table、timer、watcher 或 scheduler。
   AI migration stream 只追加 `pg-9017`，建立 runtime-only 的窄 SECURITY DEFINER admission
   authorization function，不授予 runtime 对 credential、Identity、Project、RoleBinding 或 audit 表的
   直接读写权。默认 control image/entrypoint 继续不加载 AI，Edge/Standalone closure 零变化。
2. Prompt execution transport 升级为 server-derived request：body 只允许 request/trace、parameters、
   provider/model、token/temperature/timeout 与显式 output intent；禁止 publication/generation/digest、
   Subject、Policy fence、credential identity、planned/deadline、Run/StepRun/invocation identity。
3. 首次请求由 PostgreSQL current automation head 派生 exact publication；exact replay 必须先按 durable
   request plan 找到 immutable historical publication，再验证 caller request digest。Package 后续
   upgrade/withdraw/quarantine 不会让已完成请求再次调用 Provider，也不能把旧 plan 用于新 request。
4. Route 仍先经过共享 bearer authentication、overload shield 和 Project Policy；AI admission 事务再以
   `authenticationId` 解析 exact API credential version，取得 credential/Identity advisory lock，验证
   credential/Identity active 与数据库时钟有效期，再锁定 active Project/latest RoleBinding exact fence。
5. admission 事务必须用共享 Project Policy 角色语义确认 `run.start`、`model.invoke`、`secret.use` 均为
   allow；Agent 的 `require_approval` 不得在此被降级为 allow。新 admission 在同一 SERIALIZABLE
   transaction 原子写 allowed `prompt.execute` SecurityAudit、Run、StepRun、Events 和 admission receipt；
   credential/RoleBinding/permission/audit 任一失败时零 Provider I/O 和零部分 Run。
6. exact replay 仍重新验证 current credential、Identity、Project/RoleBinding 与三权限，但不重复写
   allowed audit、不重新执行 current Package start guard、不再次调用 Provider。replay 只返回既有
   content-free receipt；live result 只返回第一次仍连接的 caller。
7. Provider authority 保持 projected read-only manifest + durable Provider binding + projected Secret
   material；route/body/env 不成为 credential authority。`durable_artifact` 只有在 ADR-0261 output
   keyring/read/retention authority 已显式装配时可达，`live_only` 不把正文写入 PostgreSQL、audit 或日志。
8. 该切片复用 `@qinglong/ai` 与 `@qinglong/cluster-control` 既有 subpath。包边界继续按部署制品、
   权限域、可选依赖和消费者裁决；workspace 保持 19 包，不能因本次多出 guard/adapter 文件拆新包。

## 被拒绝的方案

- **继续让 caller 提供 publication digest**：把 current generation 选择权留在 transport，并使 replay
  与首次执行无法采用同一 durable-plan-first 规则。
- **只依赖 admission pipeline 的一次 `model.invoke`**：不能关闭 credential revoke TOCTOU，也没有
  与 Run commit 原子的 allowed audit；三权限当前碰巧落在同一角色集合也不能替代显式契约。
- **先提交 Run，再异步补 audit 或 credential check**：会产生无当前授权或无审计的外部费用。
- **为 Prompt 建独立 API/AI service 或第二 Pool**：增加端口、证书、连接预算和故障域，没有新的
  deployment authority 价值。
- **把 Cluster Prompt 入口复用 Local `ql3-prompt`**：POSIX UID/command-file proof 不能替代多副本
  bearer identity、PostgreSQL fencing 与 HA durability。

## 接受门

- v2 exact body 拒绝 caller-supplied publication/identity/fence/credential/clock/Run 字段；
- current publication server derivation、historical exact replay、request drift conflict 和 Provider
  exactly-once；
- credential/Identity/Project/RoleBinding revoke race 与三权限/Agent approval 在 admission transaction
  内失败，零 Provider I/O、零 Run、零 allowed mutation audit；
- allowed audit 与 admission 原子提交，COMMIT response loss 以同 request 收敛且不重复计费；
- projected Provider binding/Secret、live-only redaction、durable output explicit gate；
- Cluster Control、AI、PostgreSQL 真库与完整 package/back/dependency 门；
- PostgreSQL 18.4 physical HA 证明 admission/audit 在 promotion 前同步复制、promotion 后 exact replay、
  credential/RoleBinding fence 和 content-free facts 均保持；
- Edge/Standalone 十档 artifact closure 与 workspace 19 包不增长。

## 实施证据

- Cluster Prompt route 已升级为 v2 exact body；publication digest、Principal、Policy fence、credential、
  server clock 与 Run identity 均不能由 caller 提供。route 使用进程内 UUID v4 factory 生成 mutation
  audit identity，并复用现有 authentication shield、route registry、AI composition 与 PostgreSQL Pool。
- `PostgresPluginPackagePromptExecutionService` 首次请求从 current automation publication head 派生
  publication；exact replay 先读取 immutable admission plan，再解析历史 publication。admission
  repository 的 guard 在同一 SERIALIZABLE transaction 中执行，首次写入 Run facts 前和 exact replay
  返回前都重新验证 current authority。
- `pg-9017-ai-plugin-package-prompt-product-authorization` 建立仅授予 `ql3_runtime` EXECUTE 的
  SECURITY DEFINER function；函数以数据库时钟和 advisory/row locks 验证 exact API credential
  version、active Identity、Project 与 latest RoleBinding fence，拒绝 Agent approval 语义，并在首次
  admission 同事务插入一条 content-free `prompt.execute` allowed audit。readiness 同时冻结 migration
  history、runtime role、snapshot function 与 authorization function 的精确权限。
- 定向与完整门：AI 199 pass/3 条件 skip、Cluster Control 175 pass/2 条件 skip；完整 19-package 门
  退出 0，后端 1,096 pass/2 条件 skip/0 fail。cluster dependency、Edge import、package boundary 与
  local-image audit 全部 compatible，workspace 保持 19。
- 十档 Edge/Standalone artifact closure 全部 compatible：最小 Edge 3,519,580 bytes/324 files，Edge
  Application 4,600,461 bytes/418 files，最大 Standalone Application AI 5,930,722 bytes/475 files；
  非 AI closure 不加载 AI/Cluster Prompt 产品面。
- PostgreSQL 18.4 arm64 physical HA 报告最终 `gates.passed=true`。首次 Cluster Prompt 请求只有 1 条
  allowed audit，exact replay 未重复写；RoleBinding 撤销后的新 request 为 0 条 allowed audit且零
  Provider 重打。audit/admission/finalization/content-free facts 在 promotion 前同步复制，timeline 1→2
  后完全一致；旧主 fenced、rewind 后只读重入，两控制副本恢复。隔离 HA 资源零残留，既有 CNPG
  evidence control-plane ID 未变、running、restart count 0。