qinglong/docs/adr/ADR-0273-local-ai-provider-credential-product-authority.md

ADR-0273：本机 AI Provider Credential 产品 Authority

• 状态：Accepted
• 日期：2026-08-04
• 关联：D-156、D-159、D-166、D-167、D-207、D-243、D-254、ADR-0169、ADR-0177

上下文

QingLong 3.0 已有 Project-bound Provider credential contract、可清零 Secret material、Cluster PostgreSQL catalog，以及完整 Prompt executor；但 Edge/Standalone 仍没有耐久的 Provider→SecretRef binding、credential-use audit 或受支持管理命令。ql3-local-app 的 installed AI 只能由嵌入方注入 provider loader，通用产品入口继续失败关闭。因此直接开放 Prompt CLI/HTTP 会迫使用户把 token 放进 配置、请求或进程环境，或者用测试内存 adapter 冒充生产 authority。

这个缺口不能通过新建 package、常驻管理 daemon 或把 AI migration 塞进所有路由器数据库来解决。 非 AI Edge 必须继续不安装、不加载、不迁移该能力；只有显式安装并激活 AI 的部署承担成本。

决策

1. 在既有 @qinglong/ai optional migration stream 增加 SQLite 9013，持久化 immutable Provider credential binding、append-only transition 和 content-free use audit。它不进入 QL3 base migration/capability，也不改变非 AI Profile 的表集合。
2. 新的 Local repository 留在 @qinglong/ai/local-model-provider-credential-storage，实现既有 catalog、administration、binding-source 与 credential-audit port；不让 local-sqlite 依赖 AI，也不 新建 workspace package。current state 由 (Project, provider, generation) append-only transition 推导，不维护可漂移的第二 head。
3. bind/revoke 必须由当前 strong User 通过 secret.manage Policy；同一个 SQLite BEGIN IMMEDIATE 内重新验证 credential/Identity/pepper、active Project 与 latest RoleBinding fence，检查目标 SecretRef 属于 Project 且 exact pinned/current envelope 存在，然后原子写 binding、transition 与 allowed security audit。相同 mutation exact replay；命令、audit、actor、fence 或 Secret 事实漂移 冲突并回滚。
4. 既有 local-owner-cli 增加短生命周期 ql3-model-credential，只从 deployment root 内当前 UID private 0600 command file 接受 model-credential.bind|revoke|inspect。inspect 同样在事务内复验 authority、读取 current transition、写独立 allowed audit；不存在返回 absent，不形成枚举 oracle。
5. 产品输出只包含 Project/provider/generation/state、binding revision/digest 与 transition time/digest； 禁止输出 SecretRef、Secret name/version、envelope/key/token、authentication ID、数据库路径或原始错误。
6. credential-use audit 固定 operation/Project/provider/request、binding revision/digest 与时间，不保存 SecretRef 或模型内容；相同 identity 的 exact replay允许，语义漂移失败关闭。每次 provider 请求仍 重新读取 current binding 和 Secret material，不增加 cache、watcher 或 timer。
7. 本切片只建立本机 provider authority，不提前声称 Prompt 产品入口完成。下一切片必须从这个 durable catalog、EncryptedLocalSecretService 与 active AI head 组合 ql3-prompt，不得接受 caller-supplied binding/publication/Policy fence。

被拒绝的方案

• token 放环境变量或 Prompt command：无法按 Project 隔离，容易进入日志、诊断和进程快照。
• 把 binding 写入 provider URL/policy manifest：配置文件会成为无审计 mutation authority，无法 对 COMMIT response loss 或 revoke 收敛。
• 让 local-sqlite 依赖 @qinglong/ai：会把 optional AI 反向带入最小路由器 storage closure。
• 新建 provider-credential package：没有独立制品或进程价值，违反 19-package 收敛账本。
• 常驻管理 API/watcher：增加低配设备空闲 RSS、文件描述符和攻击面；短生命周期 CLI 已足够。
• 先开放 Prompt，再补 credential authority：会把测试 adapter 或静态 token 固化为产品安全边界。

接受门

• SQLite 9013 migration/history/readiness 和 fresh/upgrade/partial-schema 失败关闭；
• bind→inspect→rebind→revoke、并发 CAS、exact replay、response-loss convergence；
• non-Owner/无 secret.manage、credential/Project/RoleBinding/Secret race 均零部分写入；
• command/output exact-shape 与 SecretRef/token/path/error 脱敏；
• AI、Owner CLI、Local application targeted tests，完整 19-package/back 门；
• dependency/package-boundary/edge-import/local-image 与十档 artifact/RSS 门证明非 AI 路由器零增量；
• PostgreSQL HA 基线保持通过；本机 optional-only 变更不冒充新的 Cluster HA 能力。

实施证据

• @qinglong/ai 的独立 SQLite AI migration stream 已加入 9013-ai-model-provider-credential-catalog；migration plan digest 为 2720c6e45f82adbb03641d1c19e8ff7e1875a763a0b53d4910a46ca308800aa0。 三张表只在显式 AI migration/activation 后存在，不进入本机 base schema。
• LocalModelProviderCredentialRepository 已实现 immutable binding、append-only transition、 current-state 推导、Secret envelope 复验、事务内 authorization guard 和 content-free use audit； bind/replay、missing Secret、stale CAS、授权重放、inspect、revoke 后使用拒绝均有真实 SQLite 门。
• ql3-model-credential 已提供 private command-file-only 的 bind/revoke/inspect。真实 Edge fixture 已通过 bind→exact replay→inspect→独立 CLI process→revoke；未激活 AI 在认证前失败关闭，无 secret.manage 的 strong User 零 transition。输出不含 SecretRef、token、credential/path 或 authentication identity。
• 定向完整包门：AI 198 pass/3 条件 skip、Owner CLI 96 pass、Local SQLite 192 pass；完整 19-package 门退出 0，后端 1,096 pass/2 条件 skip/0 fail。dependency/package-boundary/ edge-import/local-image audit 全绿，workspace 仍为 19 包。
• 十档本机制品均 compatible=true。最小 Edge 为 3,518,660 bytes/324 files/ 10,813,440 bytes RSS；最大 Standalone Application AI 为 5,917,156 bytes/475 files/ 20,480,000 bytes RSS。非 AI Edge 的 package closure 不含 @qinglong/ai。
• PostgreSQL 18.4 arm64 physical HA 基线 gates.passed=true，完成 remote_apply、timeline 1→2、旧主 fencing、pg_rewind read-only 重入与同步复制恢复；本切片没有新增 PostgreSQL migration、role、Pool、listener 或 Cluster authority。受保护 CloudNativePG 证据控制面前后保持 同一 container ID、restart count 0、running。