qinglong/docs/adr/ADR-0027-artifact-read-authorization-and-local-range-contract.md

# ADR-0027：Artifact 读取授权、存在性屏蔽与本地 Range 契约

- 状态：Proposed
- 日期：2026-07-19
- 关联：QL-RFC-0001、ADR-0024、ADR-0026

> 2026-08-12：Local/Cluster 生产读取接线由 ADR-0377 接受，Local retention 二次检查与 durable 410
> 由 ADR-0378 接受；Cluster retention 删除实现仍属于 D-291，本 ADR 的其余跨 adapter 扩展继续保持 Proposed。

## 上下文

2.x 日志 API 由全局登录或 Open API scope 保护，读取端仍接受 `path + file`，无法表达 Project 所有权、`artifact.read` 策略和 opaque Artifact identity。3.0 已把 LocalProcess 日志绑定到 `(projectId, runId, attemptId, logArtifactId)`，并用 retention tombstone 与 canonical truncation fact 保存清理和截断证据，但尚无稳定读取语义。

直接复用旧接口会产生四类问题：授权粒度不足；路径成为外部能力；文件缺失无法区分 retention 与异常丢失；文件大小等于 quota 时无法判断是否真正截断。对 edge，整文件读取还会产生与日志大小线性增长的内存峰值；对 cluster，本地路径又不是共享事实。

## 决策

### 1. API 只接受 identity 和有界 byte range

3.0 查询请求只包含 subject、Project ID、Run ID、opaque Artifact ID、offset 和 length，不接受目录、文件名、URI 或绝对/相对路径。首版本地单次读取长度上限固定为 256 KiB；offset 为非负安全整数，length 为正安全整数。

本地 reader 从 Artifact ID 派生私有 shard 和 `${artifactId}.log`，验证 root/shard 为非 symlink 目录，并以 `O_RDONLY|O_NOFOLLOW` 打开普通文件。它在打开的 fd 上采样一次 size，最多分配请求上限的 Buffer，并返回：

- `start`、`endExclusive`、`totalBytes`；
- 尚有快照内容时返回 `nextOffset`；
- 读取期间新增的 append 不进入当前响应，下一次 range 才可见；
- 文件在 stat 后异常缩短时 fail closed，不伪造完整 range。

这不是 HTTP `Range` 的最终 wire 格式；HTTP、MCP、CLI adapter 必须映射同一 application contract，不能各自直接读文件。

### 2. 数据库绑定和授权必须先于任何 Artifact 文件访问

固定顺序为：

1. 纯内存规范化 subject、Project/Run/Artifact identity 和 range；
2. metadata repository 按 `(projectId, runId, logArtifactId)` 查询 Run、Attempt 和 tombstone；
3. 只接受 `execution_owner=runtime`、`executor_type=local_process`、canonical `local-*` 绑定；
4. 调用 `artifact.read` authorizer，输入 subject、Project、Run 和 Artifact identity，不包含文件路径或内容；
5. 只有 `allow` 才能访问日志或 truncation fact；`deny` 与 `require_approval` 都不会触发 FS probe。

不存在绑定时返回内部 `not_found`，策略拒绝返回内部 `forbidden(effect)`。面向非可信调用方的 adapter 默认必须把 forbidden 和 not-found 映射为同一种不可用响应，避免通过状态、响应体、长度或 timing 暴露跨 Project 存在性；真实拒绝原因留给低敏审计。当前尚未实现 HTTP adapter，因此不能把 2.x 全局登录视为 3.0 authorizer。

### 3. 读取状态稳定区分 available、retained 与 missing

授权后 application service 返回以下领域状态：

- `available`：日志 fd 已安全打开并返回有界快照；
- `retained`：存在与 Attempt/Artifact identity 一致的 immutable tombstone，不访问已清理文件；
- `missing`：数据库仍有绑定、没有 tombstone，但本地文件不存在，表示需要运维诊断的未知丢失；
- `not_found`：请求 Project 内没有可读的 runtime/local Artifact 绑定；
- `forbidden`：内部策略结果，外部默认屏蔽。

为关闭 `metadata read → retention unlink → file open` 竞态，文件返回 ENOENT 后必须再次读取 metadata：若出现同 identity tombstone，收敛为 retained；若 identity 消失或漂移，按证据冲突 fail closed；仍无 tombstone才返回 missing。若 retention 在文件已打开后 unlink，POSIX fd 快照仍可完成 available 响应。

### 4. truncated 是严格三态

`truncation.truncated` 只能是 `true | false | unknown`：

- canonical fact 的 `quotaReached=true|false` 分别映射 true/false；
- fact 缺失映射 unknown，禁止从 size、末尾文本或退出状态推断；
- fact 的 Run/Attempt/Artifact identity 与数据库不一致时 fail closed；
- retained 始终返回 unknown，因为 ADR-0026 retention 会删除 fact，当前 tombstone 没有保存截断字段。

已知 fact 可以同时返回 bounded `maximumBytes` 和 `observedAtMs`，但不能返回 launcher capability、路径或用户输出。

### 5. edge、standalone 与 cluster 复用语义，不复用 adapter

- edge/standalone：SQLite metadata + private local range reader + local truncation fact；单次内存上限 256 KiB，无 watcher、tail timer 或目录扫描；
- cluster-control：PostgreSQL metadata + Project policy + object-store range GET/delete marker；控制面不得拼接 Worker 本地路径；
- worker：本地 spool 读取属于 Worker capability，必须由 authenticated transport、Run lease/fencing 和上传 ACK 约束。

所有实现必须通过同一 contract suite，保持状态、授权顺序、存在性屏蔽、range 边界和三态截断一致。

### 6. 当前保持 production unreachable

本切片已实现领域类型、`ArtifactReadAuthorizer`、metadata/range ports、SQLite metadata adapter、私有文件 reader 和组合 service，但没有注册到 typedi、Express/Open API、MCP、UI 或启动 lifecycle。生产接入至少还需要：

- Project/Actor 身份来源和真实 policy engine；
- forbidden/not-found wire masking、审计和 rate limit；
- content type、下载头、流式 tail/backpressure 与客户端取消契约；
- cluster PostgreSQL/object-store adapter 和 Worker transport；
- 实机权限、unlink/append、ENOSPC 和多架构 contract 测试。

## 影响

正面影响：

- 授权拒绝可结构化证明不会接触日志文件和 truncation fact；
- 调用方不再持有路径能力，单次读取内存有固定上限；
- retention、异常缺失和截断三态有稳定、可测试解释；
- edge 与 cluster 可以共享领域协议而替换存储 adapter。

代价与风险：

- 每次首次读取至少需要一次 metadata 查询和一次 policy 决策；ENOENT 竞态需要第二次点查；
- 当前 tombstone 不保存 truncation，retained 历史只能返回 unknown；
- 外部 adapter 若错误区分 forbidden/not-found，仍可能形成存在性侧信道；
- 256 KiB 是首版安全上限，后续调整必须结合 edge 内存并发预算，而不是只看单请求吞吐。

## 未选择的方案

1. **复用 2.x `path + file`**：路径是越权能力且没有 Project 绑定，拒绝。
2. **先打开文件再授权**：即使不返回内容也泄露存在性并触发敏感副作用，拒绝。
3. **一次读取完整日志**：内存随 Artifact 增长，不适合 edge，拒绝。
4. **文件不存在统一当 404**：无法解释已执行 retention，也无法暴露运维异常，拒绝。
5. **size 达到 quota 即 truncated=true**：精确写满与超额不可区分，拒绝。
6. **cluster 通过共享挂载读取 Worker 路径**：没有对象 ownership、ACK 和 fencing，拒绝。

## 验证要求

- 非法 identity/range 在 metadata、policy 和 FS 副作用前拒绝；
- deny/require-approval 时 file/fact 调用次数为零；
- available range 的 byte、offset、snapshot size、nextOffset 和 256 KiB 上限可重复验证；
- symlink file、symlink shard、非普通文件和异常短读 fail closed；
- retained 不访问 FS，ENOENT 后出现 tombstone 收敛为 retained；
- missing 与 retained 稳定区分，identity 漂移 fail closed；
- truncation true、false、unknown 和 fact identity 冲突均有测试；
- SQLite adapter 排除跨 Project、legacy owner、非 LocalProcess 和非 canonical Artifact；
- Node 22/24 类型检查和全量测试通过；production import graph 保持不可达。