qinglong/docs/adr/ADR-0220-plugin-package-installation-inventory-query.md

# ADR-0220：Plugin Package 当前安装清单查询

- 状态：Accepted
- 日期：2026-07-29
- 关联 RFC：QL-RFC-0001 D-140、D-141、D-142、D-174、D-176、D-175、D-207、D-210
- 关联 ADR：ADR-0142、ADR-0143、ADR-0144、ADR-0184、ADR-0186、ADR-0217

## 背景

QingLong 3.0 的 Plugin Package 已有以下写入和恢复链路：

| 能力 | 当前状态 |
| --- | --- |
| install / reinstall / upgrade / rollback | 已实现 |
| proposal / approval / consume / dispatch | 已实现 |
| staged / activating / failed recovery | 已实现 |
| publisher revoke / quarantine / capability withdrawal | 已实现 |
| 精确查询当前安装 | D-210 前缺失 |
| 分页查询 Project 当前安装清单 | D-210 前缺失 |
| disable / uninstall | 未定义，后续独立状态机 |

管理 CLI 和 Cluster transport 虽然能检查 proposal/approval，却不能回答“某个 Project
当前装了什么、哪个版本可用、是否已经因 publisher 撤销而隔离”。部署者只能直接查
SQLite/PostgreSQL；这既不是稳定产品 API，也会暴露内部 schema 和过宽数据库权限。

此外，安全隔离采用 append-only overlay，而不是改写 install history。一个 install
record 可以仍是 `active`，但对应 lock 已有 quarantine event 和 withdrawal receipt。
仅回显 `install.state` 会把已撤回能力误报为可用。

## 决策

### 1. 独立只读 port，不扩大 mutation authority

`@qinglong/runtime-core/plugin-package-install` 增加
`PluginPackageInstallInventoryRepository`：

- `findCurrent(projectId, packageName)`；
- `listCurrentPage({ projectId, limit, after? })`。

该接口与既有 `PluginPackageInstallRepository` 分离。查询 composition 只依赖 inventory
port，不因复用同一个具体 adapter 而取得 admit/stage/activate/fail 等写能力。

清单只读取 current head，不返回历史 revision；顺序固定为 Package name 升序，游标仅含
最后一项 Package name。core 与 Cluster 页大小为 `1..64`，使用 `limit + 1` 判定
`truncated`，禁止 offset、任意排序、模糊查询和无界数组。

### 2. 查询结果必须感知 quarantine

SQLite 和 PostgreSQL 使用相同语义：

1. 从 `(project_id, package_name)` current head 取得精确 install record；
2. 只连接同时匹配 Project、Package、installation、lock 和 install record digest 的
   quarantine event；
3. quarantine event 必须存在对应 withdrawal receipt；
4. event、receipt 与 record 的 canonical JSON、digest 和 target binding 必须重新规范化
   并完全一致。

无隔离事实时返回 `quarantine: null`。event/receipt 只有一侧存在、JSON 损坏、target
漂移或出现多个 current 结果时失败关闭，不降级成“未隔离”。

产品层派生：

- 存在完整 quarantine fact：`availability=quarantined`；
- 无 quarantine 且 install state 为 `active`：`availability=active`；
- 其他 install state：`availability=not_active`。

因此安全 availability 不由可变缓存或 install enum 推断。

### 3. Local 产品入口与低配预算

既有 `ql3-package` 增加：

- `plugin-package.installation.inspect`；
- `plugin-package.installation.list`。

命令继续使用 Owner credential、pepper、私有命令文件和 Project Policy 认证。认证成功后
才动态加载 SQLite inventory adapter；只读命令不构造 proposal、approval、dispatcher 或
Package executor service。

Profile 预算固定为：

| Profile | 默认页 | 最大页 |
| --- | ---: | ---: |
| Edge / 路由设备 | 8 | 16 |
| Standalone | 32 | 64 |

每次仍是一次命令、一个短进程、一个 SQLite authority；不增加后台 timer、watcher、
listener、缓存或常驻连接。

### 4. Cluster 管理入口

Cluster 复用现有独立 `cluster-admin` management process，不接入常驻
`cluster-control`：

- 只接受受信 transport 注入的 active `multi_factor|hardware` User principal；
- 使用目标 Project 的 `package.manage`；
- 复用 durable `plugin-package.inspect` quota；
- 由 package-manager PostgreSQL authority 执行只读 exact/keyset 查询；
- 页大小硬限 64。

Cluster client 不只校验 exact JSON shape，还校验响应 Project、Package identity、
Package name 严格递增、请求游标之后的顺序、`next` 必须等于末项，以及
availability/quarantine/failure 事实完整性。远端不能用格式正确但语义漂移的响应欺骗
operator。

### 5. 低敏产品摘要

Local/Cluster 只返回：

- installation / Project / Package / version / operation；
- state、generation、active/previous lock digest、recovery action；
- failure 摘要；
- derived availability；
- quarantine reason/mode/event/time 与 withdrawal status/receipt/time；
- record version/time/digest。

不返回 source locator、完整 manifest、approval/stage reference、authentication ID、
credential、数据库 DSN 或内部命令内容。

### 6. 不在本决策实现 disable / uninstall

正常停用和卸载不是查询，也不能等同于安全 quarantine：

- 必须定义 Task、Tool、Workflow、Prompt 与 Secret binding 的撤出顺序；
- 必须处理 durable running、completion/recovery 与新 start barrier；
- 必须保留安装、审批、执行和审计历史；
- 必须检查跨 Package/Workflow 引用；
- uninstall 必须区分逻辑退役、物理制品回收和失败恢复。

这些语义需要独立、可重放、双方言原子的状态机 RFC。D-210 不删除任何安装或历史，
也不把 quarantine 当作用户可选的 disable。

## 不采用方案

### 直接暴露数据库表

拒绝。会把 schema 变成公共 API，绕过认证、Project fence、配额、边界校验和脱敏。

### 把查询方法加入管理 mutation service

拒绝。会迫使只读入口装配 proposal、approval、dispatcher 和 executor authority。

### 全量或 offset 分页

拒绝。并发安装时会重复/遗漏，且无法给路由设备提供确定内存上限。

### 新建 inventory package 或常驻同步 daemon

拒绝。没有独立部署或依赖隔离价值，违反 D-175/D-207，并增加低配设备安装、SBOM、
空闲 RSS 和维护成本。

### 顺便删除、disable 或复用 quarantine

拒绝。删除破坏历史；quarantine 表达 publisher/lock 安全撤回，不表达用户正常退役。

## 影响

- workspace 保持 20 个 package；
- 不新增 migration、第三方依赖、进程、端口或后台资源；
- mutation repository contract 和既有写路径不变；
- Local 与 Cluster 获得一致的 current inventory 语义；
- Cluster transport public operation 从 9 个增加为 11 个；
- disable/uninstall 明确列为后续独立状态机，而不是缺省删除行为。

## 验证

1. GitNexus impact：SQLite repository 为 HIGH（24 upstream、4 direct），PostgreSQL
   repository 为 HIGH（4 upstream、2 direct）；transport normalizer 为 HIGH（6
   upstream、2 direct）；新增服务/transport/client/HA 场景入口为 LOW。实现只增加只读
   方法并保持既有 mutation 语义不变；
2. runtime-core page/cursor、SQLite exact/list、双方言共享 repository contract、
   Local 完整 Package 生命周期、Cluster service/transport/client 定向回归通过；
3. Local 生命周期在 publisher revoke 后证明 install record 仍为 active，但 inspect/list
   均输出 `availability=quarantined`、精确 reason 和 withdrawal status，且不泄露敏感
   material；
4. Cluster 三包 TypeScript 闭包通过；`cluster-admin` 全包 132 pass、1 条真实
   Kubernetes 条件 skip，TLS client 6/6，覆盖 11 个公开 operation、跨 Project、
   重复/乱序 keyset、错误 next cursor 与不完整 quarantine 响应拒绝；
5. PostgreSQL 18.4 arm64 physical HA 使用公开
   `PostgresPluginPackageInstallRepository` 在隔离后和 timeline 1→2 提升后复验
   current exact/list，event/receipt 完全一致；
6. HA 输出
   `pluginPackageQuarantineInventorySurvivesPromotion=true`，36 个具体 gate 与总
   `passed=true`；临时依赖 link 由 trap 清理，Docker 资源由 HA fixture 清理。

当前未完成证据是六个 Local Profile 的正式 bytes/files/RSS artifact matrix：它仍由
exact local-sqlite Drizzle RC 未物化阻断。该限制不影响 D-210 的 Cluster HA 结论，也
不能用从受审本机镜像临时提取的依赖替代正式 lockfile 安装与远端 CI。