qinglong/docs/adr/ADR-0368-bounded-project-run-discovery-http-api.md

ADR-0368：有界、Project-scoped 的 Run Discovery HTTP API

• 状态：Proposed
• 日期：2026-08-11
• 关联：QL-RFC-0001 D-45、D-46、D-49、D-52、D-269、D-278、D-279、D-280，ADR-0052、ADR-0349、ADR-0367

背景

Local 与 Cluster 已有同构的 GET /api/v3/projects/{projectId}/runs/{runId}，但调用方必须预先知道 runId。这使 HTTP API 无法从“最近运行”进入诊断闭环。MCP 已证明 Project-scoped keyset pagination、双方言 repository 和低敏字段白名单可用；HTTP 不应复制另一套排序、投影或存储协议。

该切片不得因增加第二条 route 再拆 package。Local 继续使用现有可选 @qinglong/local-api 单进程组合根；Cluster 继续使用现有 @qinglong/cluster-control route registry、admission pipeline 与 PostgreSQL Pool。

决策

1. Local 与 Cluster 同时增加 GET /api/v3/projects/{projectId}/runs，operation/permission 固定为 run.list/run.read。每页都必须经过 route/query validation → Authentication → Project Policy → durable security audit → credential fence（Local）→ bounded repository read。
2. query 只允许 limit、after_created_at_ms、after_run_id。limit 默认 32、最大 64；两个 cursor 参数必须同时出现，时间必须是 canonical 非负 safe integer，Run ID 必须满足现有 128 字符资源标识约束。重复、空值、未知、部分 cursor 或非 canonical decoded 数字在 Authentication 前失败关闭。Local loopback transport 额外拒绝 raw percent encoding；Cluster transport 先按 Node URL 语义解码，再对 decoded query 做 exact semantic validation，因此不宣称保留或拒绝原始编码形式。
3. Runtime Core 在现有 src/run/projection/ 增加纯 bounded-run-list-projection subpath，统一输入、limit + 1 storage fetch、排序复验、Project 遮蔽、低敏投影、hasMore 与 next。MCP qinglong.run.list 改为薄协议 adapter 并保持公开 Tool schema/错误不变；Local/Cluster HTTP 不依赖 MCP 或 Tool Registry/SemVer。
4. 返回固定 {runs, hasMore, next?}。Run item 只包含 id、taskId/revision、status/version/eventSequence、priority、execution origin/owner 和四个生命周期时间；不包含 Project、request/ref/trigger/attempt、executor、错误、Artifact、日志或 Secret 邻接字段。
5. 双方言复用现有 (project_id, created_at_ms, id) 索引与 ProjectRunListReader；不新增 migration、table、connection、transaction authority 或缓存。排序固定 created_at_ms DESC, id DESC，cursor 为上一页最后一个已返回项。
6. Local HTTP response 上限从只容纳 point read 的 4 KiB 调整为覆盖 64 条最坏字段长度低敏记录的固定 64 KiB；静态最坏 JSON envelope 为 61,516 bytes。Edge 并发仍为 4、Standalone 仍为 32，请求/URL/header/drain 上限不变。默认 headless Local artifact/image 仍不安装 local-api。
7. workspace 保持 18 package。新增代码只能进入 Runtime Core run/projection、Local API 既有 run/admission/transport/application-runtime 与 Cluster Control 既有 run/application-runtime 领域目录。不得以 route、projection、codec 或“一文件一目录”的形式制造新的 package/层级；单文件 capability 默认留在 owning domain，只有独立部署、authority、第三方运行闭包或被多生命周期复用的稳定安全叶子才允许形成 package 边界。

不采用方案

• 只给 Local 增加列表：会让相同 /api/v3 在单机和集群具有不同的基础发现闭环。
• HTTP 直接导入 MCP projection：会把 MCP SDK/Tool Registry/SemVer 闭包带入普通 API 制品。
• offset pagination：深页成本随历史增长，且并发插入时容易重复或遗漏。
• 把 cursor 编成 opaque token：首版没有签名/密钥 authority，编码并不增加可信度，反而扩大解析面。
• 返回数据库 Run row 或错误摘要：run.read 不是调试、Artifact、日志或 Secret 权限。
• 新增 run-query package/service：没有新的部署或权限边界，只增加 manifest、importer、SBOM 和低配安装成本。

完成门

• shared projection 覆盖默认/最大页、cursor、空页、排序、跨 Project/畸形 row、repository failure 与 module closure；
• Local 覆盖 canonical query、认证前拒绝、run.list audit、credential fence、真实 SQLite HTTP E2E、过载与 drain；
• Cluster 覆盖 reviewed route/operation allowlist、query、Policy/audit 顺序、真实 PostgreSQL repository contract；
• Runtime Core、MCP、Local API、Cluster Control/PostgreSQL 定向与完整 package/backend 通过；
• package/source/dependency boundary、默认 Local image、Local/Cluster artifact 与 PostgreSQL HA 不回归。

实现证据（2026-08-11）

• Runtime Core 466/466、Local MCP 38/38、Local API 19/19、Cluster Control 189 pass/2 条件 skip；18-package 完整门退出 0，backend 1,156 pass/2 条件 skip。
• workspace 仍为 18 package/1,018 source，其中 1,000 个位于 package 内部 domain/capability 目录，18 个 src/ 根文件全部是受审 public/binary entry；无 single-source、shallow-source 或 package-boundary finding。
• dependency 回归 52/52，完整 dependency audit findings=[]；MCP 只新增 @qinglong/runtime-core/bounded-run-list-projection 这一条纯读 subpath allowlist，默认 Local image 继续不安装 local-api。
• 14 个 Local Profile artifact 全部 compatible。Edge/Standalone API 分别为 5,085,520/5,085,664 bytes、518 files、57 loaded modules，RSS 增量 12,681,216/13,041,664 bytes，低于 6 MiB/640 files/24 MiB；Edge/Standalone 并发仍为 4/32。
• 最紧的 Edge/Standalone Application+AI 分别为 6,281,356/6,281,488 bytes，距 6 MiB 上限仅 10,100/9,968 bytes；预算未放宽，后续闭包增长必须先裁剪，不能通过新增 wrapper/package 转移成本。
• PostgreSQL 18.4 arm64 HA Docker contract 112 gates 全部通过，timeline 1→2，report SHA-256 为 a25e7226286f063d9b2e85a2a25c20834021627aa192e069f3bb4d40572c0447；结束后临时容器、卷、网络均为零。

固定物理路由器上的 API Profile RSS/延迟报告仍未取得，因此 ADR 保持 Proposed；该缺口不影响本轮自动化实现完成结论。