qinglong/docs/adr/ADR-0375-shared-current-task-point-read-api.md

ADR-0375：共享的 current Task point-read API

• 状态：Accepted
• 日期：2026-08-11
• 关联：QL-RFC-0001 D-06、D-08、D-13、D-17、D-28、D-75、D-85、D-87、D-157、D-239、D-253、D-257、D-262、D-279、D-280、D-285、D-286、D-287，ADR-0256、ADR-0272、ADR-0350、ADR-0373、ADR-0374

背景

D-286 已让 Local、Cluster 和 MCP 能以稳定 keyset 发现 Project 的 current Task，但客户端若持有一个 Task ID，仍必须扫描列表才能确认它当前是否存在、是否启用以及具体 revision。后续 Task start 又必须绑定明确的 current revision 与 immutable content digest，否则 discovery 与 mutation 之间的定义变化会被静默接受。

直接返回完整 TaskDefinition 不是可接受的捷径：command、public environment、SecretRef、working directory、placement、description 与 labels 都可能暴露执行细节或 secret-adjacent 内容，并会把内部 spec 格式冻结成公共 API。point read 应先提供精确 current-head identity/fence；完整 spec preview 与 Task start 继续分别评审。

决策

1. Runtime Core 在 task-definition/projection 拥有唯一 executeBoundedTaskReadProjection，输入为可信 Project ID 与一个 Task ID，只调用 TaskDefinitionSource.findCurrentTaskDefinition(projectId, taskId)。
2. 找到时只返回 found=true、taskId、current revision、name、kind、specSchema、enabled、contentDigest、createdAtMs、updatedAtMs。contentDigest 是后续 mutation 的 optimistic fence，不是执行授权。
3. 不得返回 Project、description、spec config/command/environment/placement、labels、mutationId、SecretRef 或数据库 row。合法的不存在、Task identity 不匹配与跨 Project 记录必须统一为 found=false；畸形 record、digest/time 不一致和 repository failure 必须失败关闭为 unavailable。
4. Local 与 Cluster 增加同构 GET /api/v3/projects/{projectId}/tasks/{taskId}，固定 operation task.get、permission task.read。不允许 query 或 body；Local 继续在 authentication 前拒绝非规范 path/query，Cluster 复用 route registry 的 exact path/query 编译。
5. HTTP 找不到统一返回 404 task_not_found；存储或投影不可用统一返回 503 task_query_unavailable。响应不把 Project ID 重复写入 body，Project authority 来自经过 admission 的 path binding。
6. 本机 MCP 增加 qinglong.task.get@1.0.0，输入只有 taskId，输出直接复用共享 projection。Tool 固定 effect=read、risk=low、task.read 与 5 秒上限，复用 authentication→Tool Policy→durable audit→credential confirm→同一 SQLite authority。
7. Local Application product surface 和 Local MCP database 只把既有 source 的 findCurrentTaskDefinition 加入窄 read authority；Cluster 复用 ClusterControlAssemblyInput.taskDefinitions 与现有 PostgreSQL Pool。
8. 不新增 workspace package、第三方依赖、migration、表、索引、数据库连接、listener、sidecar、timer、watcher、cache 或写 authority。历史 revision read、完整 spec preview、Task start、input payload 与 mutation 继续需要独立 ADR。
9. D-285/D-286 的 18-package、14 Profile artifact、真实 Local image、完整 backend/packages、dependency/package boundary 与 PostgreSQL HA 门不得放宽。

不采用方案

• 让客户端扫描 Task list：深链接成本随 Task 数量增长，也不能获得明确的 current digest fence。
• 返回完整 TaskDefinition：会泄露命令、环境、SecretRef 和部署细节，并提前冻结扩展 spec 协议。
• 只返回 revision、不返回 digest：同一 revision 的损坏或错误 adapter 映射无法被客户端/后续 start 计划绑定。
• 把 task.get 合入 task.list query：混合 collection 与 resource 语义，增加游标和 not-found 歧义。
• 只实现 HTTP 或只实现 MCP：会让人类客户端与 AI 客户端拥有不同的 current-head/fence 语义。
• 新增 Task query package/service：纯投影没有独立部署、authority 或重依赖隔离价值。

完成门

• Runtime Core 覆盖 found/absent、字段脱敏、disabled Task、跨 Project、畸形 record、digest/time drift 与 repository failure；leaf import 不加载 Tool Registry/SemVer。
• Local route、transport、admission、product authority 与真实 SQLite HTTP 覆盖 task.read、pre-auth query rejection、credential confirm、durable task.get audit、404 masking 和同一 storage authority。
• Cluster route、registry 与 production composition 使用既有 TaskDefinitionSource/Pool，并覆盖 Policy、audit、404 masking、无 query/body 与响应上限。
• MCP 覆盖精确 Tool schema、task.read admission、durable audit、credential confirm、真实 stdio/SQLite current Task read，并证明只调用共享投影。
• Runtime Core、Local SQLite、Local API、Local Application、Local MCP、Cluster Control、双方言相关测试、完整 backend/18-package、14 Profile artifact、真实 Local image与 PostgreSQL HA 全绿。

验收证据

• Runtime Core 486/486、Local SQLite 213/213、Local API 39/39、Local MCP 45/45、Local Application 45 pass/4 条件 skip、Cluster Control 204 pass/2 条件 skip；完整 18-package clean build/test 退出 0，完整 backend 1,163 pass/2 条件 skip、0 fail。Local HTTP 使用真实 SQLite authority 持久化 task.get audit，MCP stdio 使用同一 SQLite current Task source；Cluster production composition 使用既有 PostgreSQL source/Pool。
• workspace 保持 18 package/1,035 source，其中 1,017 nested/18 个受审根入口，singleSourcePackages=[]、 shallowSourcePackages=[]。package boundary 正反向门 62/62，dependency audit findings=[]；没有新增 package、 第三方依赖、migration、表、索引、连接、listener、timer、watcher、cache 或写 authority。
• 14 个 Profile artifact 全部 compatible=true。默认 Edge/Standalone 仍为 2,385,220/2,385,298 bytes、288 files、 50 loaded modules；Application、Adopted、AI 与 Application AI 档相对 D-286 精确不变。选择 Local API 的 Edge/Standalone 为 3,538,918/3,539,062 bytes、416 files、80 modules，相对 D-286 增加 5,412/5,412 bytes、 2 files、2 modules；选择 MCP 的 Edge/Standalone 为 7,161,579/7,161,687 bytes、776 files、213 modules， 相对 D-286 增加 7,364/7,364 bytes、2 files、2 modules。未选择 API/MCP 的低配部署不承担该增量。
• 真实 arm64 Local Application image 为 10 package/380 files/3,284,889 bytes，默认不含 Local API、MCP、AI 或 Cluster package；Edge 128 MiB/64 PIDs 与 Standalone 256 MiB/256 PIDs 均以 UID/GID 65532:65532、只读根、 network=none 完成 active→graceful stop，SQLite integrity ok。临时 image 已删除。
• PostgreSQL 18.4 arm64 HA 通过 112 gates，timeline 1→2，报告 SHA-256 d2f02a7cd67a712e5fe3e2152c8c3afdefe9680d51c6c0ab108c6882ac7c841c；旧主 fence、promotion、pg_rewind/ rejoin 与 fresh replica 收敛后 Docker 容器、网络、卷零残留。
• GitNexus 刷新为 47,031 nodes/106,513 edges/1,853 clusters/295 flows。四个新增生产符号均为 LOW：Local route 1 direct/1 process，Cluster route 1 direct/2 total，MCP Tool 1 direct，共享投影 0 indexed upstream；跨 package export 未形成的调用边由三端定向测试、完整 package、真实 SQLite/MCP 与 artifact 门补强。无 HIGH/CRITICAL。