ADR-0377：Profile-aware Run Attempt 日志范围读取

状态：Accepted
日期：2026-08-12
关联 RFC：QL-RFC-0001 D-289
前置决策：ADR-0027、ADR-0367、ADR-0376

上下文

Task Start 已能在 Local 与 Cluster 创建可执行 Run，产品入口也能读取 Run、Event、Step 并请求取消，但调用方仍无法从同一 Project-scoped 产品面读取某个 Attempt 的执行日志。早期 back/runtime 已验证本机 metadata-first 授权、私有文件 Range 与截断三态，但它不在 QingLong 3.0 package 生产图中，也没有 Cluster 对象存储实现。

直接恢复 2.x 的 path + file 会把路径当作外部 capability；把整份日志编码进 JSON 会让内存与日志大小线性增长；把 Local 与 Cluster 强行放到同一存储 adapter，又会使控制面依赖 Worker 本地路径。低配路由设备和集群节点需要共享语义，但必须拥有不同的单次窗口与存储实现。

决策

1. 同一产品路由与只读权限

Local 与 Cluster 提供同构入口：

GET /api/v3/projects/{projectId}/runs/{runId}/attempts/{attemptId}/log?offset={n}&length={n}

operation：run.log.read
permission：artifact.read
response schema：qinglong/run-attempt-log-read-result@v1
offset 默认为 0；length 默认为当前 Profile 窗口
请求只接受 Project、Run、Attempt identity 和有界范围，不接受 Artifact ID、路径、URI、bucket 或 object key

Policy、durable security audit 与 credential confirmation 必须先于 Run/Attempt metadata 和 Artifact 存储访问。对非可信 HTTP 调用方，Policy deny、require-approval、跨 Project、不属于该 Run、legacy owner、错误 executor 和不存在均返回相同的 404，不形成存在性 oracle；真实结果只进入低敏审计。

2. 共享 application contract，不共享存储 adapter

runtime-core 定义唯一的 Run Attempt 日志读取服务和 byte-range port。服务复用现有 RunRepositoryReader.findRunById/findAttemptById，依次验证：

Run 属于请求 Project 且 executionOwner=runtime；
Attempt 属于请求 Run；
executor 与当前 Profile 一致；
Attempt 绑定 canonical local-* 或 wlog-* Artifact ID；
range 规范化且不超过调用 Profile 的上限；
只有上述数据库事实成立后才调用存储 reader。

Local adapter 从 opaque local-* ID 派生私有 shard，拒绝 symlink、非普通文件、非当前进程 owner、多 hard link、异常短读和 identity 不一致的 truncation fact。Cluster adapter 先用现有 immutable S3 HEAD 校验 identity digest、length、content type、checksum metadata，再执行单次有界 Range GET；控制面从不拼接 Worker 路径。

S3-compatible provider 必须在最终对象 COPY 后，通过启用 checksum 的 HEAD 返回 canonical ChecksumSHA256；只返回调用方可写 metadata 而不能独立证明对象内容的实现不在兼容集合内，adapter 必须失败关闭，不能退化为信任 metadata 或 ETag。

3. Profile 窗口和资源上限

共享协议硬上限为 256 KiB，但部署档位收紧实际窗口：

Local Edge：默认 16 KiB，最大 32 KiB；
Local Standalone：默认/最大 32 KiB；
Cluster Control：默认 64 KiB，最大 256 KiB。

当前 HTTP transport 只返回 JSON，因此 content 使用 Base64，并同时返回 byte range、总长度和下一 offset。Local 的 32 KiB 上限保证编码和元数据仍低于既有 64 KiB response hard limit；Cluster 保持低于既有 1 MiB 默认 response limit。reader 只分配请求窗口，不启动 watcher、tail timer、cache、额外 listener、Pool 或 S3 client。

4. 状态与失败语义

200 available：返回当前文件/对象快照内的有界 bytes、start、endExclusive、totalBytes 和可选 nextOffset；
202 pending：合法远端 Attempt 已绑定日志，但对象尚未在 upload-before-completion 协议中发布，或 Attempt 尚未产生 Artifact identity；
404 artifact_not_found：不存在、越权或 identity/executor 不匹配的统一外部遮蔽；
503 artifact_unavailable：数据库、文件安全检查、对象存储或证据一致性无法证明。

truncated 保持 true | false | unknown。Local 只相信 launcher canonical fact；Cluster 只相信 immutable S3 metadata；禁止从 size、尾部文本或退出状态推断。offset 等于或超过当前快照末尾时返回空的 available range，并把 start 收敛到 totalBytes，便于轮询而不制造 416 竞态。

5. 本批明确不闭环 retention

本批不新增 tombstone table、delete marker、retention lifecycle 或对象删除权限。ADR-0027 的 retained/missing 竞态和 ADR-0026 retention 仍是独立后续切片。没有 tombstone 时，Local 的已绑定文件缺失和终态 Cluster 对象缺失都按 503 处理，不能伪装成已执行 retention；因此 ADR-0027 在 retention 完成前保持 Proposed。

6. package 与部署边界

不新增 workspace package、第三方依赖、migration、table/index、数据库连接或常驻资源；
contract 放入 runtime-core 既有 Run 能力目录；Local reader 放入 local-execution 既有 Artifact 能力目录；S3 reader 扩展 cluster-control 既有 immutable store；
默认 headless Local 不加载文件 reader；只有可选 Local API product surface 通过 application authority 获得已构造 capability；
Cluster 复用 production Worker artifact binding 的同一 S3 client/store；未配置对象存储时 route 保持存在并失败关闭为 503；
MCP 本批不读取日志，避免在 Agent 面扩大敏感数据能力。

被否决的替代方案

恢复 path + file：路径成为跨 Project capability，拒绝。
整文件返回或服务端 tail 长连接：内存、连接和后台资源无界，不适合 Edge，拒绝。
固定所有 Profile 为 256 KiB：Base64 后突破 Local 64 KiB transport 门，拒绝。
Cluster 读取 Worker 共享挂载：绕过 immutable upload、checksum 与 fencing，拒绝。
为日志读取新建微包或 metadata 表：既有 Run/Attempt authority 足够，本批不制造薄 package，拒绝。
将 missing 当 retention：没有 durable tombstone 无法证明，拒绝。

验收

shared contract 覆盖 identity/range、Project/Run/Attempt/executor 绑定、pending/available/missing 与截断三态；
Local adapter 覆盖 symlink、owner/link count、append snapshot、短读、空/越尾 range 和 fact identity 冲突；
S3 adapter 覆盖 HEAD identity/checksum、精确 Range、abort、404、响应长度/Content-Range 漂移和终态缺失；
Local/Cluster HTTP 覆盖 route/query、artifact.read、durable audit、deny/not-found 遮蔽、202/200/400/404/503；
默认 headless Edge closure 不增加；Local API 增量仍满足 64 KiB response、4 in-flight 与 128 MiB/64 PID 门；
完整 package/backend、dependency/package boundary、Profile artifact、真实 SQLite+HTTP、S3-compatible integration、PostgreSQL HA 与 Local image 门全部通过后，状态才可改为 Accepted。

Accepted 证据

Runtime Core 494/494、Local Execution 35/35、Local API 45/45、Local Application 45 pass/4 platform skip、Cluster Control 215 pass/2 conditional skip；完整 18-package build/test 退出 0。
backend 1,163 pass/2 skip/0 fail；package boundary、dependency boundary 与 Edge import audit 全部 compatible。workspace 仍为 18 package、1,045 source、1,027 nested/18 reviewed root entry，无 single-source 或 shallow package。
真实 SQLite+HTTP 已覆盖认证、Policy、durable audit、credential confirmation、Attempt metadata 与本地私有文件 Range 的完整顺序；Local 文件 adapter 的 symlink、权限、hard-link、短读、append snapshot、越尾空读与 truncation identity drift 全部通过。
S3 单元门覆盖 checksum/metadata/ETag/Content-Range 漂移、短体与超长体；固定摘要 minio/minio@sha256:14cea493d9a34af32f524e538b8346cf79f3321eff8e708c1e2960462bd8936e 的真实 KMS/SSE、条件 promotion、重放、HEAD 与 Range GET 通过。不能在 COPY 后返回 ChecksumSHA256 的旧 provider 被实测失败关闭。
PostgreSQL 18.4 arm64 HA 通过 112 gates，timeline 1→2，报告 SHA-256 为 61bea38e3a4f66884b9642c2fc1944dd7084f70ceb358d6d3fea8c11d5d33b65。
14 个 Edge/Standalone Profile artifact 全部 compatible。Edge Application API 为 3,596,457 bytes/423 files/84 loaded modules，距 6 MiB 门仍有 2,694,999 bytes；依赖闭包不包含 Cluster、PostgreSQL 或 AWS SDK。
当前源码构建的 arm64 Local image 为 10 package/385 files/3,331,225 bytes。Edge 128 MiB/64 PIDs 与 Standalone 256 MiB/256 PIDs 均在 non-root、read-only root、network-none 下 active、20 events、graceful stop，SQLite integrity 为 ok。
本批没有新增 package、第三方依赖、migration、table/index、连接、listener、timer、watcher 或 cache；Artifact retention/tombstone 仍由 ADR-0027 后续闭环。

8.9 KiB Raw Blame History Unescape Escape