qinglong/docs/adr/ADR-0349-bounded-local-mcp-project-run-discovery.md

# ADR-0349：有界、Project-scoped 的本机 MCP Run 发现

- 状态：Accepted
- 日期：2026-08-10
- 关联 RFC：QL-RFC-0001 D-05、D-06、D-08、D-13、D-17、D-28、D-75、D-85、D-87、D-157、D-257、D-259、D-260、D-261
- 关联 ADR：ADR-0041、ADR-0052、ADR-0063、ADR-0087、ADR-0088、ADR-0345、ADR-0346、ADR-0347、ADR-0348

## 背景

`qinglong.run.get` 与 `qinglong.run.events.list` 已能读取一个已知 Run 的低敏快照和事件，但调用方必须先知道 `runId`。这使桌面 Agent 和本机 AI Client 不能从“最近运行”开始诊断，只能依赖用户复制内部标识，尚未形成可用的只读发现闭环。

发现能力必须保持 Project 隔离和固定资源上限，不能通过 offset 扫描放大历史成本，也不能返回输入、输出、命令、错误、触发者、请求、幂等键或 Artifact reference。SQLite 与 PostgreSQL 已有 `(project_id, created_at_ms, id)` 索引，因此本批不需要 migration。

这也是对 workspace 结构的再次校验：协议、投影和双方言 adapter 具有不同领域 owner，但都属于既有 Runtime Core、Local SQLite 和 Cluster PostgreSQL package；为它们新建微包会增加 importer、构建、SBOM 与低配设备闭包成本。相反，把实现继续堆在 `src/` 根层也会混淆 public entrypoint 与领域实现。

## 决策

在既有本机 MCP sidecar 增加第三个只读 Tool：`qinglong.run.list@1.0.0`。输入固定为 `{after?, limit?}`；`limit` 默认 32、最大 64。`after` 是服务端返回的 `{createdAtMs, runId}`，查询按 `createdAtMs DESC, id DESC` 执行严格 keyset 分页，并最多读取 `limit+1` 条。

输出固定为 `{runs, hasMore, next?}`。每个 Run 只包含：

- `id`、`taskId`、`taskRevision`；
- `status`、`version`、`eventSequence`、`priority`；
- `executionOrigin`、`executionOwner`；
- `createdAtMs` 以及存在时的 `queuedAtMs`、`startedAtMs`、`finishedAtMs`。

输出不得包含 `projectId`、Task name/snapshot、trigger、actor、request/idempotency、parent/retry identity、input/output reference、cancel/error detail、Attempt、Event payload、Artifact/Log、Secret、Policy 或数据库 row。adapter 返回跨 Project、乱序、重复位置、越过 cursor 或超量结果时，projection 统一失败关闭。

每次 Tool call 继续复用同一个 admission 顺序：authentication → exact `tool.call:qinglong.run.list` + `run.read` Policy → durable audit → credential `confirm()` → Project-scoped bounded read。MCP 不缓存结果，不增加连接、timer、watcher、listener 或 background service。

Runtime Core 在 `run/` 领域目录新增 profile-neutral `ProjectRunListReader`/cursor/query，在 `tool-execution/` 新增低敏 Tool projection；Local SQLite 与 Cluster PostgreSQL 在各自 `run/` adapter 增加同契约查询。公开能力使用精确 subpath，不扩大 Runtime Core root facade。

## Package 与目录规则

Package 以独立部署、authority、依赖隔离、可替换 adapter 或多消费者 shared leaf 为边界，不以文件数为边界。包内源码遵循：

1. `src/` 根层只允许受审 binary entry、public export 或确有跨领域意义的 shared infrastructure；
2. 领域实现进入 `src/<domain-or-capability>/`，公开 subpath 直接映射 owning module；
3. 单文件/全根层 package 必须提供独立边界证据，否则结构门失败；
4. 不为“目录整齐”新建微包，也不把纯 facade 移入虚构的 `public-api/` 目录；
5. root file/line hard cap 只允许 ratchet，不允许随新增功能自动增长。

本批新增代码全部进入 `run/` 与 `tool-execution/`。当前 17 个 package、992 个 source 中 966 个 nested、26 个 root（97.4% nested），`singleSourcePackages=[]`、`shallowSourcePackages=[]`；新增 Runtime Core root export 曾使 160 行 hard cap 超出 1 行并被 gate 拒绝，随后改为精确 subpath，证明门禁能实际阻止根层继续膨胀。

## 被否决方案

1. 客户端传 Project ID：会把租户范围从可信 MCP 配置退化为调用参数。
2. offset/page-number 分页：历史增长后成本不稳定，并在并发插入时产生漂移。
3. 返回完整 Run record：会泄露命令关联、actor、错误与 Artifact reference，并让未来字段自动进入公共面。
4. 复用 Package Workflow 管理列表：其 Package/Workflow authority、审计事务和输出模型不适合通用 Run discovery。
5. 新建 `run-list` package：没有独立部署或依赖边界，只会形成微包。
6. 把新协议直接放到 `runtime-core/src/`：会扩大根 facade 和领域混杂，结构 hard cap 已明确禁止。

## 验收证据

- Runtime Core 453/453：Definition、默认/最大页、exact cursor、低敏字段、严格降序、跨 Project/乱序/超量故障关闭。
- Local SQLite 204/204：真实 migration/runtime repository、同时间 ID tie-break、跨 Project 排除、连续两页。
- Cluster PostgreSQL 286 pass/1 条件 skip：参数化 SQL、严格降序 keyset、limit 与 row normalization。
- Local MCP 8/8：三 Tool 静态发布、逐调用 permission/admission/audit 顺序、真实 stdio/API Credential/SQLite discovery E2E。
- package boundary 与 dependency audit compatible；17 package、无单文件/浅层 package、992 source 中 966 nested。
- 十二档 artifact 全部 compatible。最紧 Standalone Application AI 为 6,262,567 bytes/637 files，距离 6 MiB 上限 28,889 bytes；MCP Edge/Standalone 为 9,800,548/9,800,656 bytes、941 files、187 loaded modules，RSS 增量 43,008,000/43,171,840 bytes。
- 未新增 workspace package、production dependency、migration、表、索引、数据库连接或后台资源。

## 后续约束

Run filter/search、跨 Project 聚合、事件订阅、日志/Artifact 内容和任何写 Tool 必须另立 ADR，并证明索引、租户隔离、字段脱敏、限流、授权、审计及设备预算。新领域优先进入既有 owning package 的能力目录；只有 package ledger 的边界证据成立时才允许增加 package。