qinglong/docs/adr/ADR-0274-authenticated-local-plugin-package-prompt-product-entry.md

# ADR-0274：受认证的本机 Plugin Package Prompt 产品入口

- 状态：Accepted
- 日期：2026-08-04
- 关联：D-156、D-157、D-159、D-167、D-207、D-243、D-251、D-254、ADR-0260、ADR-0270、ADR-0273

## 上下文

QingLong 3.0 已有 generation-bound、content-free 的 Prompt execution plan、SQLite admission/
finalization、Model Gateway、可选 AI feature head、加密 Local Secret，以及 Project-bound durable
Provider credential binding；但这些仍只通过嵌入式 `loadProviders` 测试组合可达。部署者没有一个可以
在 Edge/Standalone 上直接执行已发布 Prompt 的受支持产品入口。

直接把 executor 暴露为 CLI 仍不安全：caller 可以伪造 publication、Policy fence、Provider→Secret
binding 或 planned time；认证与 admission 分事务还会留下 credential/RoleBinding revoke TOCTOU。
另一方面，为 Prompt 新建 daemon、HTTP listener 或 workspace package 会把空闲内存、连接、供应链与
运维成本推给低配路由器。

## 决策

1. 在既有 `@qinglong/local-owner-cli` 增加一次性 `ql3-prompt`，仅接受 deployment root 内当前 UID
   所有、mode `0600` 的私有 command file。命令固定 current strong User；inspect 需要 `run.read`，
   execute 同时需要 `run.start`、`model.invoke` 与 `secret.use`。
2. caller 只提供 Project/Package/Prompt、request/trace identity、瞬态 parameters、Provider/Model、
   有界 token/temperature/timeout 与显式输出意图。publication、installation/lock/generation/
   materialized revision/digest、requested User、Policy fence、planned/deadline time 和
   Provider credential binding 均由当前 durable authority 派生；command 禁止携带 SecretRef、token、
   authorization header、publication JSON/digest、plan、Run/StepRun/invocation ID 或 Policy fence。
3. 首次执行从 exact current active automation publication 派生 Prompt；exact replay 先读取 durable
   admission plan，再按其 publication digest 读取历史 immutable publication，因此 withdrawal/
   replacement 不会导致已完成请求再次调用 Provider。replay 必须重新通过当前 credential 与 Project
   Policy，并验证相同 caller request 的参数/Provider/Model/output digest。
4. SQLite Prompt admission 在自己的 `BEGIN IMMEDIATE` 内调用受认证 guard：重新验证 API credential、
   active Identity、pepper、active Project、latest RoleBinding 与 exact Project/Binding fence，并原子写
   allowed `prompt.execute` SecurityAudit；首次和 replay 都必须匹配同一 audit semantic。current Package/
   lifecycle/quarantine/publication/Prompt guard、Run/StepRun/Event/admission receipt 与该 audit 同事务。
5. Model Provider authority 由 deployment root 内 canonical、只读 provider/policy manifest 与
   D-254 durable binding 组合。每次请求通过 `BoundModelProviderCredentialProvider` 重新解析 binding，
   再由 `EncryptedLocalSecretService` 从同一个 SQLite authority 和本机 keyring 取得可清零 material；
   Prompt command、provider manifest、环境变量和进程参数都不得成为 credential authority。
6. 产品入口只打开一个 SQLite connection，Model Gateway、Prompt admission、publication、Policy、
   Secret 和 credential repository 共用其有界 operation authority。命令完成后先 drain gateway，再关闭
   authority；不新增 daemon、listener、Pool、timer、watcher、scheduler cadence 或后台恢复循环。
7. 默认 `live_only` 只把模型结果返回当前 CLI caller，durable SQLite 继续只保存摘要与 receipt；exact
   replay 返回 content-free receipt 且不承诺重放正文。`durable_artifact` 只有在显式 key/output product
   authority 装配后才允许，不能静默降级为明文数据库或日志。
8. 能力继续留在既有 AI/Local SQLite/Owner CLI subpath，不新增 workspace package。包是否独立由生产
   制品、权限边界、可选依赖与真实消费者决定，不能按源码文件数机械合并或继续拆分；D-255 保持
   workspace 为 19 包。

## 被拒绝的方案

- **继续要求 `loadProviders` 注入**：这是嵌入测试 seam，不是部署者可审计的 credential 产品边界。
- **command 接受 publication/plan/fence/binding**：把服务端 durable authority 外移给 caller。
- **认证后再用无 guard repository admission**：RoleBinding 或 credential 可在事务窗口内被撤销。
- **环境变量或 manifest 内 token**：扩大 Secret 泄漏面，绕过 D-254 binding/audit/revoke 语义。
- **为 Prompt 新建 package/daemon/API**：没有独立常驻价值，并增加路由器空闲 RSS 与攻击面。
- **把 `ql3-local-command-file` 等单文件包按数量机械并入 Owner CLI**：它是多个本机产品共享、零业务依赖
  的私有输入协议；合并会反向引入高权限闭包。单文件只是审计信号，不是合并结论。

## 接受门

- private command exact-shape、路径/权限/owner/symlink 边界，以及禁止 caller-supplied authority 字段；
- active AI head 前置门，non-AI Edge 不加载 Prompt 产品闭包；
- strong User 与三项 Project permission，credential/Identity/pepper/Project/RoleBinding revoke 竞态在
  admission 事务内失败且零 Provider I/O、零部分 Run/audit；
- current publication 服务端派生、withdrawal 后 exact replay、参数/Provider/Model/output drift 冲突，
  Provider 对同一完成请求恰好一次；
- durable binding→EncryptedLocalSecretService→authorization lease 全链路，Secret/token/path/
  authentication identity 不进入 command result、durable evidence或错误；
- 首次 live result、content-free replay、drain/close 次序与 Edge/Standalone 有界 RSS；
- AI、Local SQLite、Owner CLI 定向和完整 19-package/back 门，dependency/package-boundary/
  edge-import/local-image 与十档 artifact/RSS；PostgreSQL HA 仅回归基线，不虚假声明本机能力为 Cluster
  HA 新能力。

## 实施证据

- `@qinglong/local-owner-cli` 已提供 `ql3-prompt` 与受审 command subpath；首次执行从 current
  publication 派生 plan，exact replay 从 durable plan 回查 immutable historical publication。真实
  SQLite 测试证明首次只调用一次 Provider、返回 live result，replay 不再次调用 Provider且只返回
  content-free receipt。
- admission mutation guard 已进入同一 `BEGIN IMMEDIATE`：credential、active Project/latest
  RoleBinding、三项 permission 与 exact fence 在提交前重新验证，allowed SecurityAudit 与
  Run/StepRun/admission 原子提交。测试在 provider authority 装载窗口撤销 RoleBinding，结果为零
  Provider I/O、零 admission、零 Run、零 allowed audit，并留下一个低敏 failure audit。
- 生产 credential 链已通过真实 loopback OpenAI-compatible 请求验证：durable Provider binding →
  `EncryptedLocalSecretService` → private keyring → read-only canonical provider manifest；HTTP
  Authorization 使用解密 material，command/result/durable plan 均不包含 token、SecretRef 或路径。
- 定向门：AI 198 pass/3 skip、Local SQLite 192 pass、Local Application 39 pass/3 skip、Owner CLI
  100 pass；完整 19-package 门退出 0，后端 1,096 pass/2 skip/0 fail。package-boundary、cluster
  dependency、Edge import 与 local-image audit 全部 compatible。
- 十档制品门全部 compatible：最小 Edge 3,519,580 bytes/324 files，Edge Application
  4,600,461 bytes/418 files，最大 Standalone Application AI 5,918,783 bytes/475 files；非 AI
  application closure 不包含 `@qinglong/ai` 或 Prompt Owner CLI。
- PostgreSQL 18.4 arm64 HA 回归总 `gates.passed=true`，Prompt admission/finalization 的 exact
  replay、提升前复制、promotion 后存活、Policy revoke fence 与 content-free durable record 门均为
  true。隔离 HA 资源已清理；受保护 CNPG 控制面 ID、running 状态与 restart count 0 前后不变。