qinglong/docs/adr/ADR-0371-bounded-project-run-step-list-http-and-mcp-api.md

# ADR-0371：有界、Project-scoped 的 Run StepRun HTTP 与 MCP API

- 状态：Accepted
- 日期：2026-08-11
- 关联：QL-RFC-0001 D-279、D-280、D-281、D-282、D-283，ADR-0367、ADR-0368、ADR-0369、ADR-0370

## 背景

D-282 已让 Local、Cluster 与 MCP 观察 RunEvent 时间线，但事件只能解释聚合状态变化，不能给出 Workflow DAG 中每个 Step 的当前状态、重试次数和父子关系。Cluster 的 Plugin Package Workflow 专用管理路由已有 StepRun 查询语义，通用 Run API 与本机 MCP 却仍缺少同一能力。直接复用专用管理模块会把 Package/Workflow identity、管理审计与更大的闭包带入基础诊断面；在三个产品面复制投影则会产生字段和分页漂移。

## 决策

1. Local 与 Cluster 增加同构 `GET /api/v3/projects/{projectId}/runs/{runId}/steps`，固定 operation `run.steps.list`、permission `run.read`。不得接受 body；query 只允许 canonical `after_step_key`、`after_step_run_id` 与 `limit`，cursor 必须成对，默认 32、最大 64。
2. Runtime Core 在既有 `run/projection/` 中拥有唯一 `boundedRunStepListProjection`。它先用 `RunRepositoryReader.findRunById` 验证 Project 归属，再调用只读 `StepRunRepository.listByRun`；不存在与跨 Project 返回同一 `found=false`，repository、shape、cursor、identity、state 或 order 异常失败关闭。
3. 成功响应只包含 `steps`、`hasMore`、`next`。每项只公开 `id`、`parentStepRunId`、`stepKey`、`kind`、`required`、`status`、`version`、`attemptCount`、`readyAtMs`、`startedAtMs`、`finishedAtMs`、`resultCode`、`createdAtMs`、`updatedAtMs`。禁止 `definitionRef`、`definitionDigest`、`inputRef`、`outputRef`、`approvalRequestId`、`errorSummary`、`lastMutationId` 与 `stepRunDigest` 越过投影。
4. 顺序固定为 `(stepKey ASC, id ASC)` keyset；`next` 只在 `hasMore=true` 时返回最后一条已返回记录的 `{stepKey, stepRunId}`。该 API 是每页重新认证、授权和审计的 forward-only 当前视图，不宣称跨页快照。
5. HTTP 的不存在和跨 Project 统一映射为 404 `run_not_found`。Local 复用 loopback listener、Edge 4/Standalone 32 并发、Bearer、Project Policy、持久 Audit、credential/Pepper confirm 与唯一 SQLite authority；Cluster 复用 route registry、两阶段 admission、持久 Audit 与既有 PostgreSQL Pool。
6. 本机 MCP 增加低风险只读 `qinglong.run.steps.list` Tool，输入输出语义与共享投影一致。MCP read database 只暴露 `StepRunRepository.listByRun`；HTTP 不导入 MCP/Tool Registry，MCP 不取得 StepRun `apply` mutation authority。
7. Local Application product-surface contract 把 Run 与 StepRun 能力收窄为所需只读方法：Run 只允许 `findRunById/listRunsByProject/listEvents`，StepRun 只允许 `listByRun`。底层仍复用同一已打开 storage authority，不新增连接或第二个 repository owner。
8. 不新增 workspace package、第三方依赖、migration、index、repository method、数据库连接、listener、sidecar、timer、watcher、cache 或 authority。实现必须落在既有 Runtime Core、Local API、Local MCP、Local SQLite 与 Cluster Control 领域目录。
9. D-281 的全部文件、flash、module 与 RSS 门不得放宽。完整 backend/packages、14 artifact、默认 Local image、package/dependency boundary、Local Edge/Standalone live contract 与 PostgreSQL HA Docker 门必须通过。

## 不采用方案

- **复用 Plugin Package Workflow administration**：它绑定 Package/Workflow identity 和管理事务，不是通用 Run 低敏查询叶。
- **直接返回完整 StepRunRecord**：definition、input/output、approval 和 error 字段可能是 secret-adjacent 或内部恢复事实。
- **只实现 HTTP 或只实现 MCP**：会让人在面板与 AI 排障时观察到不同的 Run 事实。
- **offset、无界列表或按更新时间排序**：DAG Step identity 天然由稳定 `(stepKey,id)` 排序，offset 会随变化和规模放大。
- **新增 Step/timeline package**：共享纯投影没有独立 deployment、authority 或版本边界，不足以承担第 19 个 package 成本。
- **新增表或索引**：双方言现有 `StepRunRepository.listByRun` 与 `(run_id,step_key,id)` keyset 已满足查询。

## 完成门

- Runtime Core 覆盖默认/最大 page、cursor、严格 order、duplicate、状态时间不变量、低敏字段、缺失/跨 Project 与 repository failure；
- Local route、transport、admission、product-surface contract 与真实 SQLite HTTP 覆盖同一 storage authority、安全 admission、404 遮蔽和最大响应；
- Cluster route、registry 与 production composition 复用既有 runtime `runs/stepRuns`；
- MCP Tool definition、adapter、admission 与真实 SQLite MCP composition 证明只读能力且不加载 mutation authority；
- 完整源码、制品、真实 Local image 与 PostgreSQL HA 门全绿，并记录最终 package/source、artifact、module、RSS 与 Docker 证据。

## 实现与验证证据

- Runtime Core 已提供唯一 `boundedRunStepListProjection`，Local/Cluster HTTP 与 `qinglong.run.steps.list` MCP Tool 均只做协议适配。Runtime Core 476/476、Local API 27/27、Local MCP 41/41、Cluster Control 196 pass/2 环境条件 skip、Local Application 45 pass/4 平台条件 skip、Local SQLite 209/209。
- 真实 SQLite HTTP 覆盖 Bearer、Project Policy、持久审计、跨 Project 遮蔽、成对 cursor 与同一 storage authority。构造全部低敏字段上界的 64 条 StepRun 响应为 48,895 bytes，低于固定 64 KiB transport 门。
- 完整 18-package clean build/test 退出 0，backend 1,160 pass/2 skip/0 fail。workspace 为 18 package/1,026 source，其中 1,008 nested、18 个 `src/` 根文件全部是登记的 public/binary entry；package boundary 与 cluster dependency audit 均为 `compatible=true`、`findings=[]`，没有 single-source 或 shallow-source package。
- 14 个 Edge/Standalone artifact 全部 compatible。最紧 Edge/Standalone Application+AI 分别为 6,269,636/6,269,768 bytes、646 files、133 loaded modules，距 6 MiB 尚余 21,820/21,688 bytes；RSS 分别为 21,233,664/21,364,736 bytes，未放宽 D-281 门。Edge/Standalone MCP 分别为 9,878,070/9,878,178 bytes、955 files、210 modules。
- AI-excluded arm64 Local image（`sha256:8e1b1852ef101f4bb6ad900109dec7d700ece3fcf44ba7db9e958bbe3609cebc`）为 477 files/4,705,667 bytes、精确 10-package closure；同一镜像在 Edge 128 MiB/64 PIDs 与 Standalone 256 MiB/256 PIDs 的 read-only、network-none 门均 graceful stop 且 SQLite integrity `ok`。
- PostgreSQL 18.4 arm64 HA 合同通过 112 gates，timeline 1→2；私有报告 SHA-256 为 `c83fb5eb49fccbb6e5a6b3bdcd8a86c9fea88e73b995624d82b9c4b71b9f0d97`，离线证据审计 `compatible=true`、`findings=[]`，测试容器、卷与网络清理后均无残留。
- 本切片只增加既有领域内的投影、route/adapter、只读 composition 与测试；没有新增 package、第三方依赖、migration、index、连接、listener、sidecar、timer、watcher、cache 或写 authority。