qinglong/docs/adr/ADR-0374-shared-bounded-task-discovery-http-api.md

# ADR-0374：共享、有界的 Task Discovery HTTP API

- 状态：Accepted
- 日期：2026-08-11
- 关联：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-262、D-279、D-280、D-285、D-286，ADR-0350、ADR-0367、ADR-0368、ADR-0373

## 背景

Local、Cluster 与 MCP 已能观察 Run、RunEvent 和 StepRun，但通用 HTTP 客户端仍不能先发现当前 Project 的 Task。面板、CLI 或 API client 因此必须从内部数据库或 MCP 复制 `taskId`，还不能形成“发现 Task → 选择 Task → 后续启动 Run”的产品链。

本机 MCP 已实现低敏 `qinglong.task.list`，SQLite 与 PostgreSQL 的 `TaskDefinitionSource` 也都拥有按 `taskId` 严格递增的 current-head keyset 分页。继续在 HTTP 端复制投影会形成字段、游标和失败语义漂移；把 MCP Tool/Registry 引入普通 HTTP 又会污染默认 Local 和 Cluster 制品。

## 决策

1. Runtime Core 在 `task-definition/projection` 拥有唯一 `executeBoundedTaskListProjection`。输入为 `{after?: {taskId}, limit?}`，默认 32、最大 64；输出为 `{tasks,hasMore,next?}`，顺序固定为 `taskId ASC`。
2. 每项只公开 `taskId`、current `revision`、`name`、`kind`、`specSchema`、`enabled`、`updatedAtMs`。不得返回 Project、description、spec config/command、labels、mutationId、contentDigest、Secret reference 或存储 row。
3. disabled Task 必须保留并显式返回 `enabled=false`，不得在投影层过滤后无界补页。投影拒绝跨 Project、越过 cursor、乱序、重复、超量、错误 continuation、畸形 current record 与 repository failure。
4. Local 与 Cluster 增加同构 `GET /api/v3/projects/{projectId}/tasks`，固定 operation `task.list`、permission `task.read`。query 只允许 `after_task_id` 和 `limit`；不存在 body，非法 query 在 authentication 前拒绝。
5. Local 复用 loopback listener、Edge 4/Standalone 32 admission concurrency、Bearer、Project Policy、durable audit、credential/Pepper confirm 与 application 已打开的唯一 SQLite authority。Local Application 只向 product surface 暴露 `TaskDefinitionSource.listTaskDefinitions`。
6. Cluster 复用 route registry、两阶段 admission、durable audit、现有 PostgreSQL Pool 与 `ClusterControlAssemblyInput.taskDefinitions`；不新增管理 listener、Pool 或缓存。
7. MCP `qinglong.task.list` 保持名称、版本、输入输出和 admission 不变，但降为共享投影的协议 adapter；Runtime Core projection 不导入 Tool Registry、MCP SDK 或 SemVer。
8. 不新增 workspace package、第三方依赖、migration、表、索引、数据库连接、listener、sidecar、timer、watcher、cache 或写 authority。Task point read、spec 展示、Task start 和任何 mutation 仍需独立 ADR。
9. D-285 的 14 Profile、可达 JavaScript、文件、flash、module、RSS 与真实 Local image 门不得放宽；完整 backend/packages、package/dependency boundary 和 PostgreSQL HA 必须继续通过。

## 实现证据

- Runtime Core 已实现唯一 `executeBoundedTaskListProjection`；Local API、Cluster Control 和既有 MCP Tool 均只作协议 adapter。SQLite 真实 HTTP 路径覆盖 Bearer、`task.read` Policy、durable `task.list` audit、credential confirm 与同一 TaskDefinition authority；Cluster production composition 复用既有 PostgreSQL source/Pool。
- Runtime Core `481/481`、Local MCP `41/41`、Local Application `45 pass/4 skip`、Local API `36/36`、Cluster Control `200 pass/2 skip`；完整 18-package clean build/test 退出 `0`，backend 为 `1,163 pass/2 skip`。dependency/package boundary 均 compatible。
- workspace 仍为 18 package、1,031 source，其中 1,013 个实现文件位于嵌套领域目录、18 个为受审根入口；无 single-source/shallow package。本切片只新增 Runtime Core、Local API、Cluster Control 各一个嵌套实现文件，没有新增 package 或根目录平铺文件。
- 14 个最终 Profile artifact 全部 compatible，未提高任何 cap：基础 Edge/Standalone 为 `2,385,220/2,385,298` bytes、230 个可达 JavaScript、50 loaded modules；Application+API 为 `3,533,506/3,533,650` bytes、78 modules；Application+AI 为 `4,211,374/4,211,506` bytes、133 modules，距 6 MiB 门仍有 `2,080,082/2,079,950` bytes；MCP 为 `7,154,215/7,154,323` bytes、211 modules。
- 真实 arm64 Local image 为 UID/GID `65532:65532`、AI excluded，精确 inventory 为 10 package/380 files/3,284,889 bytes；Edge 128 MiB/64 PIDs 与 Standalone 256 MiB/256 PIDs 均在 read-only root、network none 下完成 20-event active→graceful stop，SQLite integrity 为 `ok`。
- PostgreSQL HA Docker 门在 PostgreSQL `18.4`/arm64 上通过 112 gates，primary timeline `1→2`，报告 SHA-256 为 `e6e02a78d08ec387e57a9246f3175cd1bc1f05952711da584b3aa5e93dffe05c`。没有新增依赖、migration、连接、listener、timer、cache 或写 authority。

## 不采用方案

- **复制 MCP 投影到两个 HTTP package**：会形成三份字段与分页安全规则。
- **HTTP 直接调用 MCP Tool**：把 Tool Registry、SemVer/MCP 协议和可选 sidecar 依赖带入普通 API。
- **只实现 Local 或只实现 Cluster**：同一 `/api/v3` 在部署梯度间漂移，客户端必须维护两套能力。
- **返回完整 TaskDefinition**：命令、config 和 labels 可能含 secret-adjacent 内容，并提前冻结内部 spec。
- **过滤 disabled Task**：底层按 `taskId` 分页，投影过滤会造成页大小不确定或无界补读。
- **新增 Task query package/service**：纯投影没有独立部署、authority 或依赖隔离价值。

## 完成门

- Runtime Core 覆盖默认/最大页、稳定 cursor、字段脱敏、disabled Task、跨 Project、乱序/重复/超量、continuation drift 和 repository failure；leaf import 不加载 Tool Registry/SemVer。
- Local route、transport、admission、product-surface authority 与真实 SQLite HTTP 覆盖 `task.read`、pre-auth query rejection、credential confirm、durable audit 和同一 storage authority。
- Cluster route、registry 与 production composition 使用既有 `TaskDefinitionSource`/Pool，并覆盖 Project Policy、audit 和最大响应。
- MCP 既有 Tool schema与 stdio E2E 保持不变，并证明只调用共享投影。
- Runtime Core、Local API、Local Application、Local MCP、Cluster Control、双方言相关测试、完整 backend/18-package、14 Profile artifact、Local image 与 PostgreSQL HA 门全绿。